Taking a Screenshot of a Full Browser Window with Selenium WebDriver
Capture the visible Selenium browser window, distinguish it from a full-page image, and automate reliable screenshots in Python.
In Selenium Python, save the currently visible browser window with driver.save_screenshot("screenshot.png"). This captures the current browsing context as a PNG. It does not automatically mean the entire document below the fold. For a full-document image, Selenium’s Python Firefox API provides driver.save_full_page_screenshot("full_page.png").
Choose the screenshot scope first
| Goal | Use | Scope |
|---|---|---|
| Capture what is visible in the current browser window | driver.save_screenshot(path) |
Current window viewport, PNG |
| Receive visible-window PNG bytes | driver.get_screenshot_as_png() |
PNG bytes in memory |
| Receive visible-window Base64 | driver.get_screenshot_as_base64() |
Base64 string |
| Capture the complete document | driver.save_full_page_screenshot(path) |
Firefox Python API, PNG |
| Make the browser larger | driver.maximize_window() |
Window geometry only |
| Use operating-system fullscreen | driver.fullscreen_window() |
Window-manager fullscreen, similar to F11 |
The standard screenshot endpoint is documented in Selenium’s WebDriver window documentation. The Python Chromium and Firefox APIs document the file, bytes, Base64, and Firefox full-page methods in their respective API references.
Prerequisites
- Install Selenium:
python -m pip install selenium - Install a supported browser such as Chrome or Firefox.
- Use a recent Selenium 4 release and allow Selenium Manager or your environment to provide the matching driver.
The examples below show Python because the title uses Selenium WebDriver with Python APIs. The same distinction applies in other language bindings, but full-document support must be checked for the exact browser and binding.
Capture the visible full browser window in Python
from selenium import webdriver
options = webdriver.ChromeOptions()
# options.add_argument("--headless=new") # Uncomment for headless runs.
with webdriver.Chrome(options=options) as driver:
driver.get("https://example.com")
ok = driver.save_screenshot("screenshot.png")
if not ok:
raise RuntimeError("Selenium could not write screenshot.png")
save_screenshot writes a PNG of the current window. Call it after navigation and after any application-specific readiness condition your page requires.
Save through the alternate file method
from selenium import webdriver
with webdriver.Chrome() as driver:
driver.get("https://example.com")
if not driver.get_screenshot_as_file("screenshot.png"):
raise RuntimeError("Screenshot file could not be written")
Keep the image in memory
from selenium import webdriver
with webdriver.Chrome() as driver:
driver.get("https://example.com")
png_bytes = driver.get_screenshot_as_png()
with open("screenshot.png", "wb") as image_file:
image_file.write(png_bytes)
Return Base64 instead of a file
from selenium import webdriver
import base64
with webdriver.Chrome() as driver:
driver.get("https://example.com")
encoded = driver.get_screenshot_as_base64()
png_bytes = base64.b64decode(encoded)
with open("screenshot.png", "wb") as image_file:
image_file.write(png_bytes)
Control the browser window before capturing
from selenium import webdriver
with webdriver.Chrome() as driver:
driver.get("https://example.com")
driver.maximize_window()
driver.save_screenshot("maximized-window.png")
maximize_window() changes the available window geometry. It does not stitch together content below the viewport.
from selenium import webdriver
with webdriver.Chrome() as driver:
driver.get("https://example.com")
driver.fullscreen_window()
driver.save_screenshot("fullscreen-window.png")
Fullscreen is a window-manager operation similar to pressing F11. Operating systems, window managers, headless mode, and remote sessions can produce different viewport dimensions, so do not assume a fixed pixel size from maximize or fullscreen alone.
Capture a full document in Firefox
from selenium import webdriver
with webdriver.Firefox() as driver:
driver.get("https://example.com")
driver.save_full_page_screenshot("full-page.png")
save_full_page_screenshot is documented by Selenium’s Python Firefox API for a full-document PNG. Keep the .png extension. The related get_full_page_screenshot_as_file method reports True when the file operation succeeds and False on an I/O error.
from selenium import webdriver
with webdriver.Firefox() as driver:
driver.get("https://example.com")
if not driver.get_full_page_screenshot_as_file("full-page.png"):
raise RuntimeError("Full-page screenshot file could not be written")
Do not generalize this Firefox Python method to Chromium or every other Selenium binding without documentation for that combination. The reviewed Selenium references do not establish a complete cross-browser matrix.
Wait for the page state you intend to capture
A screenshot records the state at the instant Selenium asks the browser for an image. Navigation alone may not mean that a single-page application, image, animation, or lazy-loaded section is ready.
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
with webdriver.Chrome() as driver:
driver.get("https://example.com/dashboard")
WebDriverWait(driver, 20).until(
EC.visibility_of_element_located((By.CSS_SELECTOR, "main.dashboard"))
)
driver.save_screenshot("dashboard.png")
- Wait for a stable selector that represents the content you need.
- For images, wait for the relevant element and, when necessary, confirm its natural dimensions with JavaScript.
- Disable or wait out animations when pixel comparison matters.
- Use a deterministic viewport and browser mode in CI.
These are test-design practices; Selenium’s screenshot method does not promise that animations, lazy loading, or dynamic data have settled.
Common problems and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Image shows only the top portion of a long page | A current-window screenshot was requested | Use Firefox Python’s full-page method when that browser and binding are appropriate, or capture sections separately. |
| Fullscreen image is still not a full document | Fullscreen changes window geometry, not document scope | Choose a full-document API. |
| Screenshot is blank or shows a loading state | Capture ran before application content was ready | Wait for a meaningful element or application-ready condition. |
| Unexpected image dimensions | Window manager, headless mode, device scale factor, or remote session differs | Set window size explicitly where supported and record the runtime environment. |
save_screenshot returns false |
File path or filesystem write failed | Use an existing writable directory, check permissions, and verify the returned boolean. |
| Full-page method is missing | Wrong browser, binding, or API scope | Confirm you are using Selenium Python Firefox and consult the exact binding’s documentation. |
| Driver or browser cannot start | Browser/driver setup or CI sandbox issue | Install the browser, allow Selenium Manager to resolve a driver, or configure a compatible driver explicitly. |
| Screenshot differs between runs | Responsive layout, fonts, time-dependent data, ads, or animations changed | Fix viewport, locale, timezone, data, fonts, and waits; capture after a stable state. |
Reliability and performance checklist
- Reuse one driver for related captures instead of launching a browser for every image.
- Use explicit waits with bounded timeouts so failures are diagnosable.
- Write to unique paths when parallel jobs run.
- Close drivers with a context manager or a
finallyblock. - Keep screenshots as PNG when exact pixels matter; convert later if your pipeline needs another format.
- For very tall pages, consider memory use and downstream image limits. A full-document image can be substantially larger than a viewport capture.
- In remote execution, the screenshot bytes travel from the browser session to the client, so network latency and session stability affect total time.
When an API is easier than managing a browser
Selenium is useful when you need browser interaction, assertions, or test-specific state. For repeatable URL-to-image jobs, a screenshot API removes browser and driver lifecycle work.
Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF.
cURL:
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 details. ScreenshotNeo can accept cookie banners before capture and remove more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. It also supports full-page capture with lazy images loaded, CSS-selector element capture, device presets or custom viewports, retina scale, custom CSS and JavaScript, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, caching, signed links, asynchronous jobs, bulk capture, usage reporting, and PDF output. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots, and every feature is available on every plan. Create a free ScreenshotNeo account.
FAQ
Does save_screenshot capture the browser chrome?
No. Selenium captures the page in the current browsing context, not the operating system’s tab bar, address bar, or other browser chrome.
Is maximize the same as full page?
No. Maximize changes window geometry. Full page includes document content below the viewport and requires a suitable full-document method.
Can I save a JPEG directly with Selenium’s Python method?
The documented Python file methods save PNG screenshots. Convert the PNG afterward if your workflow requires JPEG.
Why does Firefox have a full-page method in this guide?
The reviewed Selenium Python Firefox API documents that method explicitly. Support depends on the browser and language binding.
Should I use Selenium or ScreenshotNeo?
Use Selenium when the screenshot is part of an interactive browser test. Use ScreenshotNeo when you want a URL-to-image or PDF request without managing browser drivers, with cleanup, billing verdicts, and an MCP option for AI agents.
