If your Selenium screenshots come out black when using headless Chrome, the fix is usually to set window-size in the Chrome options and, if that fails, to disable GPU acceleration or switch to the new headless mode. This article explains why black screenshots happen and gives you step-by-step fixes that work with current Chrome and Selenium versions.
Why Headless Chrome Screenshots Turn Black
Headless Chrome runs the same rendering engine as regular Chrome, but it has no visible window. When Selenium takes a screenshot, it asks the browser to capture the current viewport. If the viewport has a size of 0×0, or if the GPU process fails to initialize in the headless environment, Chrome may render nothing—resulting in a black image.
Common triggers include:
- Missing
window-sizeargument—headless Chrome defaults to 800×600, but some versions ignore it unless explicitly set. - GPU acceleration issues on Linux servers or virtual machines.
- Using the old headless mode (
--headless) instead of the new one (--headless=new). - Taking a screenshot before the page has fully loaded or after the browser window was minimized.
- CSS animations or WebGL content that don’t render in headless mode without special flags.
Fix 1: Set Window Size Explicitly
The most common fix is to pass a window size in the Chrome options. Without it, headless Chrome may use a default size that doesn’t match the actual viewport, causing the screenshot to be black.
- Create your Chrome options object.
- Add the argument
--window-size=1920,1080(or your desired resolution). - Also set the window size programmatically after starting the browser:
driver.manage().window().setSize(new Dimension(1920, 1080)). - Take the screenshot after the page has fully loaded (use explicit waits).
Example in Python:
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
opts = Options()
opts.add_argument('--headless')
opts.add_argument('--window-size=1920,1080')
driver = webdriver.Chrome(options=opts)
driver.get('https://example.com')
driver.save_screenshot('page.png')
Fix 2: Disable GPU and Use New Headless Mode
If setting the window size doesn’t help, the problem is often GPU acceleration. In headless mode, Chrome may try to use the GPU for rendering, but on servers or virtual machines there is no GPU available, so the renderer fails silently.
- Add
--disable-gputo your Chrome options. This forces software rendering. - Use the new headless mode: replace
--headlesswith--headless=new. The new mode is more stable and supports more features, including better screenshot behavior. - If you still see black screenshots, add
--no-sandbox(especially on Linux) and--disable-dev-shm-usageto avoid shared memory issues.
Example:
opts.add_argument('--headless=new')
opts.add_argument('--disable-gpu')
opts.add_argument('--no-sandbox')
opts.add_argument('--disable-dev-shm-usage')
Fix 3: Wait for Page Load and Take Screenshot Correctly
Sometimes the screenshot is taken before the page is painted. Headless Chrome may report that the page is loaded, but the actual rendering is delayed. Use explicit waits to ensure the page is fully rendered.
- Use WebDriverWait to wait for a specific element or for
document.readyStateto be ‘complete’. - If you’re using Selenium 4, you can also use
driver.get_screenshot_as_png()instead ofsave_screenshot()—both should work, but sometimes one behaves differently. - If your page has images or iframes, wait for those to load as well.
Example wait:
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.common.by import By
WebDriverWait(driver, 10).until(EC.presence_of_element_located((By.TAG_NAME, 'body')))
driver.save_screenshot('page.png')
Comparing Old vs New Headless Mode
Chrome 112 introduced the new headless mode (--headless=new), which uses the same browser process as regular Chrome. The old headless mode (--headless) is a separate, stripped-down implementation that has known issues with screenshots, especially with WebGL and some CSS features.
- Old headless: Faster startup, but fewer features and more rendering bugs.
- New headless: More stable, supports extensions, and better screenshot fidelity.
- If you’re on Chrome 112 or later, always try
--headless=newfirst.
For Selenium 4, you can also use the ChromeOptions class to set binary location and arguments. If you’re using Selenium 3, the same options apply via DesiredCapabilities.
Common Mistakes and Misconceptions
One common misconception is that the screenshot is black because the page is not loaded. While that can happen, the more likely cause is a rendering issue. Another mistake is using --start-maximized in headless mode—this doesn’t work reliably; you must use window-size.
Also, some users set the window size in the options but then call driver.maximize_window(), which can override the size and cause issues. Avoid maximizing in headless mode.
If you’re using a remote WebDriver (e.g., Selenium Grid), ensure the node has the same Chrome version and that the browser binary is correctly configured. Sometimes the remote node runs in a container without a display, which can cause black screenshots.
Alternative Approaches
If the above fixes don’t work, consider these alternatives:
- Use a different screenshot method:
element.screenshot()for a specific element instead of the full page. - Use Chrome DevTools Protocol (CDP) directly via Selenium 4’s
execute_cdp_cmdto capture a screenshot. - Switch to a different browser like Firefox headless (which has its own quirks) or use Playwright, which has better headless screenshot support.
- If you’re on a Linux server, install
xvfband run Chrome in non-headless mode with a virtual display—this often solves rendering issues.
For example, using CDP:
import base64
from selenium.webdriver.chrome.options import Options
opts = Options()
opts.add_argument('--headless')
driver = webdriver.Chrome(options=opts)
driver.get('https://example.com')
res = driver.execute_cdp_cmd('Page.captureScreenshot', {'format': 'png'})
with open('page.png', 'wb') as f:
f.write(base64.b64decode(res['data']))
Frequently Asked Questions
Why is my screenshot black even with window-size set?
If you’ve set window-size but still get black screenshots, the issue is likely GPU or headless mode. Try adding --disable-gpu and using --headless=new. Also, ensure you’re not calling driver.manage().window().maximize() after setting the size.
Does headless Chrome support screenshots of WebGL content?
WebGL content can be tricky. In old headless mode, WebGL often renders black. The new headless mode (--headless=new) supports WebGL better, but you may need to add --use-gl=swiftshader to force software WebGL rendering.
Can I take a full-page screenshot in headless Chrome?
Yes, but Selenium’s default screenshot captures only the viewport. For full-page screenshots, you need to use CDP’s Page.captureScreenshot with captureBeyondViewport: true, or use a library like Selenium’s full_page_screenshot (available in Selenium 4 for some drivers).
Why does the screenshot work in headed mode but not headless?
Headed mode has a real display and GPU, so rendering works normally. Headless mode may lack GPU acceleration or use a different rendering path. The fixes above (disable GPU, new headless mode) usually resolve this.
Is there a difference between save_screenshot and get_screenshot_as_png?
Both capture the same viewport. The difference is that save_screenshot writes directly to a file, while get_screenshot_as_png returns the image as a byte string. Functionally, they should produce identical results, but if one fails, try the other.
What if I’m using Selenium Grid and the node returns black screenshots?
Ensure the node has the same Chrome version and that the browser binary is correctly configured. Sometimes the remote node runs in a container without a display, which can cause black screenshots. Try adding the same flags (--headless=new, --disable-gpu) to the node’s Chrome options.
Related
General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.
More in this bed
- How to Turn Off Shutter Sound on iPhone
- VPN Setup on iPhone SE: Step-by-Step Guide
- Fix Internet Not Working on Windows 11
- Fix Right Click Not Working in Firefox
- Compare Two Columns with Comma Separated Values in Excel
- How to Limit Ad Tracking on iPhone Apps