How to Block Image Loading in Selenium
Block image requests in Selenium with browser-specific settings, understand the tradeoffs, and troubleshoot common issues in Chrome and Firefox.
To block images in Selenium, configure the browser before it starts. Selenium has no single cross-browser image-blocking switch: Chrome uses Chrome-specific options and preferences, while Firefox accepts browser profile preferences. The Chrome image preference commonly used for this is profile.managed_default_content_settings.images set to 2; because the official sources cited here do not confirm that exact key, check it against your current Chrome version before relying on it. Selenium’s pageLoadStrategy is separate: it changes when navigation returns, but does not block image requests.
1. Block images in Chrome with Selenium
ChromeDriver accepts Chrome-specific configuration through ChromeOptions. A commonly used Chrome profile preference blocks images for the session. This Python example shows where the preference belongs and how to start a browser session:
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
options.add_experimental_option(
"prefs",
{"profile.managed_default_content_settings.images": 2},
)
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()The preference is browser-specific, not a Selenium standard. The official ChromeDriver documentation explains how Chrome options carry preferences, and Chrome’s content settings define image loading as allow or block, with allow as the default. The exact profile preference key above is widely used, but should be validated with the Chrome build and driver version used in your environment. [ChromeDriver capabilities and ChromeOptions] [Chrome content settings]
What the setting does and does not do
- It tells Chrome to block image content for the configured browser profile.
- It applies to the browser session created with these options; configure each worker or remote browser session separately.
- It does not prevent CSS backgrounds, video, fonts, scripts, or other resource types from loading.
- A site may still reserve image dimensions or show placeholders, so page layout can differ from a fully loaded page.
2. Block images in Chrome with Node.js
With Selenium’s JavaScript bindings and ChromeDriver, pass the same preference through Chrome options. Install the Selenium package and ensure Chrome and its driver are available in the runtime:
const { Builder } = require('selenium-webdriver');
const chrome = require('selenium-webdriver/chrome');
(async function main() {
const options = new chrome.Options();
options.setUserPreferences({
'profile.managed_default_content_settings.images': 2,
});
const driver = await new Builder()
.forBrowser('chrome')
.setChromeOptions(options)
.build();
try {
await driver.get('https://example.com');
console.log(await driver.getTitle());
} finally {
await driver.quit();
}
})();If your Selenium binding version does not expose setUserPreferences, use its current Chrome options API to pass the prefs object. Binding APIs evolve, so consult the Selenium documentation for the installed version rather than silently falling back to an unverified constructor signature.
3. Firefox: inject preferences, but verify the image key
Firefox’s WebDriver options support a prefs object. That mechanism is documented, but the research available for this article did not verify the current Firefox preference that disables images. To avoid giving you a copy-paste value that may have changed or may not be supported, first confirm the preference in current Mozilla documentation for your Firefox version, then pass that verified name and value through options.
from selenium import webdriver
from selenium.webdriver.firefox.options import Options
options = Options()
# Replace with the image preference name and value verified
# for the Firefox version deployed in your environment.
options.set_preference("VERIFIED_IMAGE_PREFERENCE", "VERIFIED_VALUE")
driver = webdriver.Firefox(options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()This is a deliberate template, not runnable image blocking until the placeholder preference is replaced. Firefox preferences can be injected before startup; see the MDN firefoxOptions reference for the documented options mechanism. Do not assume a Chrome preference name or numeric value works in Firefox.
4. Choose between blocking images and returning sooner
If the goal is faster navigation rather than preventing image downloads, consider Selenium’s page load strategy. The default normal waits for the page load event. eager returns at DOMContentLoaded while other resources, including images, may still load. none does not wait for a particular ready state. Neither blocks image fetching. [Selenium Browser Options]
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
options.page_load_strategy = "eager" # navigation wait behavior only
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
# Wait explicitly for the page state or element your task needs.
finally:
driver.quit()With eager or none, scripts that immediately inspect image-dependent content can race the page. Add an explicit wait for the specific element or state required by the task. Do not treat a successful return from get() as proof that all assets are finished.
5. Set up a repeatable run
- Choose the browser. Image blocking is configured in that browser’s options or profile, not in a universal Selenium capability. Selenium communicates through browser-specific WebDriver implementations. [Selenium Getting Started]
- Set preferences before creating the driver. Changing options after the session starts generally does not reconfigure the running profile.
- Use a fresh session when validating. A persistent or preconfigured profile may contain settings that conflict with the preferences you expect.
- Check the outcome on a known page. Inspect whether an image element has loaded, but distinguish a blocked request from a missing image URL or a lazy image that was never requested.
- Restore normal image loading where needed. Use a separate browser options configuration for workflows that need visual or image-dependent content.
For remote Selenium, the browser runs on the remote end. The browser-specific option has to reach that browser session. The exact capability forwarding rules depend on the remote provider, so check that provider’s documentation and verify the effective browser configuration on the remote machine.
6. Options, limits, and edge cases
| Need | Use | Watch for |
|---|---|---|
| Prevent Chrome image content from loading | ChromeOptions preference in the session profile | Preference key is Chrome-specific; validate against the deployed version. |
| Configure Firefox | Firefox options prefs |
Confirm the exact image preference and value from current Mozilla documentation. |
| Return from navigation earlier | eager or none page load strategy |
Does not block requests; add explicit waits for needed page state. |
| Block other traffic too | Use a browser-specific network or request interception capability if supported by your browser and tooling | Not covered by the image preference; behavior varies by browser and driver. |
Blocking image elements does not necessarily mean every visual asset is absent. A CSS background image may follow different content handling; SVG can appear as an image or inline markup; canvas may be drawn by script; and a service worker or cache may affect what you observe. Lazy-loaded images may not be requested until scrolled into view, so a page that appears to have no image traffic on initial load may simply not have reached the lazy-load threshold.
Image blocking can alter layout and application behavior. Some pages calculate card sizes after image load, use images as clickable controls, or rely on image requests as part of client-side state. If the automation tests visual layout, image rendering, or user-visible behavior, blocking images changes the thing being tested. Use it when images are genuinely incidental to the task.
7. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Chrome still downloads images | The preference did not reach Chrome, the key is unsupported by the installed version, or a different profile/session was launched. | Confirm the ChromeOptions object is attached to the driver before startup. Test with a fresh session and verify the preference against the current Chrome build. |
| ChromeDriver rejects options | Malformed preferences, incompatible option syntax, or a binding API mismatch. | Check the installed Selenium binding’s Chrome options API and pass a dictionary/object under the documented preferences mechanism. |
| Firefox launches but images remain | The preference name or value is unverified or ineffective for that Firefox version. | Look up the current Mozilla image preference and set it with Firefox’s documented prefs mechanism. Do not reuse the Chrome key. |
| Page is faster but images still appear | eager or none was mistaken for a blocker. |
Configure the browser’s image setting; use page load strategy only to tune navigation waiting. |
Elements are missing after using none |
Automation queried the DOM before the application reached the needed state. | Wait for a concrete selector or condition rather than assuming navigation completion. |
| Some images appear intermittently | Cache, lazy loading, CSS backgrounds, or application-specific rendering can complicate observation. | Repeat with a clean session, scroll to trigger lazy loading when relevant, and inspect the resource type and loading path. |
| Works locally, not remotely | The options were applied to a local browser or omitted from the remote session capabilities. | Pass browser options through the remote session setup and verify the remote browser’s effective configuration. |
8. Performance, reliability, and cost
Blocking images can reduce image transfer and decoding work when a page would otherwise fetch many large assets. The actual improvement depends on the page, network, cache, and whether image work was on the critical path; there is no universal speedup figure. A page may still be slow because of JavaScript, CSS, fonts, APIs, or server response time.
For reliable automation, prefer the smallest change that matches the task. Keep image blocking isolated to jobs that do not need images, use explicit waits for required DOM state, and pin compatible browser and driver versions in repeatable environments. When diagnosing a failure, first separate navigation waiting from resource blocking: they are different controls.
There is no per-image Selenium service charge; the operational cost is the browser compute, network traffic, and time consumed by each run. Blocking assets can lower network use but may invalidate results if the workflow depends on visual content. Measure your own workload before changing concurrency or timeouts.
9. Or skip the browser setup
If the task is to capture a page screenshot rather than interact with it, ScreenshotNeo provides a website screenshot API and MCP server. Make a single request to capture a page:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo API documentation for request options. Cookie banners, newsletter popups, and chat widgets are removed before the shot, and each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page info, and capture PDFs. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free 1,000 screenshots per month, with no card required.
10. FAQ
Does blocking images make Selenium screenshots blank?
It can remove image content from the rendered page, but text, layout, CSS, and other resources may still render. The exact appearance depends on how the site builds its page.
Can I disable images for only one navigation?
The preference is applied to the browser session/profile. For a different policy, create a separate driver session with different options instead of assuming a per-navigation toggle.
Is eager the same as disabling images?
No. It changes when navigation returns. Images and other resources may continue loading after that point.
Will image blocking work on every Selenium browser?
No single setting is established across browsers. Configure the relevant browser through its WebDriver options and verify the exact preference for the browser version you use.
