How to Capture a Full-Page Selenium Screenshot in Firefox Headless

To capture a full-page screenshot with Selenium in headless Firefox, navigate to the page and call Firefox’s save_full_page_screenshot() method. It writes the full document to a PNG file; save_screenshot() captures only the current window.

Minimal Python example

Install Selenium with python -m pip install selenium, and make sure Firefox and a compatible geckodriver are available in your environment. Then run:

from pathlib import Path
from selenium import webdriver
from selenium.webdriver.firefox.options import Options

output = Path("full_page.png").resolve()

options = Options()
options.add_argument("--headless")

driver = webdriver.Firefox(options=options)
try:
    driver.get("https://example.com")
    saved = driver.save_full_page_screenshot(str(output))
    if not saved:
        raise OSError(f"Could not write screenshot to {output}")
    print(f"Saved screenshot to {output}")
finally:
    driver.quit()

Selenium documents this Firefox method as saving a full-document screenshot of the current window to a PNG file. The path should end in .png. It returns True on success and False for an I/O error. Use an absolute path when you are unsure what the process’s working directory is. See the Selenium Firefox WebDriver API.

Wait for the content you need

The screenshot method captures the document as it exists when called. A successful browser navigation does not necessarily mean that an application has finished rendering data, images, or other content loaded asynchronously. Wait for a page-specific signal before capture.

from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait

# After driver.get(url):
WebDriverWait(driver, 20).until(
    EC.presence_of_element_located((By.CSS_SELECTOR, "main article"))
)
saved = driver.save_full_page_screenshot(str(output))

Choose a selector that appears only when the content you need is present. The example waits for an article element; adapt it to the target site. This is a readiness check, not a guarantee that every image or third-party request has finished.

Choose the right screenshot output

Method	Result	Use it when
save_full_page_screenshot(path)	Full-document PNG file	You want the whole page saved directly to disk.
get_full_page_screenshot_as_file(path)	Full-document PNG file	You want the file-returning API variant.
get_full_page_screenshot_as_png()	PNG bytes	Your application will store or process the image.
get_full_page_screenshot_as_base64()	Base64-encoded PNG	An interface you are integrating with expects a base64 string.
save_screenshot(path)	Current-window screenshot	You only need what is visible in the current window.

For a full-page screenshot, use one of the Firefox full-page methods. The file method is simplest when you want a PNG on disk. Use bytes or base64 when your code owns the next step, such as writing to a storage service or returning image data. The Selenium API documents these full-page output forms; see the Firefox WebDriver API.

Handle long pages and lazy-loaded content

A full-document capture includes content beyond the visible window, but a screenshot call does not promise to trigger a site’s application-specific lazy-loading behavior. Images or sections that load only after scrolling may still be missing if the page has not loaded them yet.

1. Wait for the initial page content using a selector or another page-specific condition.
2. If required content loads on scroll, scroll through the page in steps and allow the site to respond.
3. Wait for the particular images or sections you need to appear.
4. Call the Firefox full-page screenshot method after that preparation.

Very long pages can produce large image files and take longer to capture or transfer. Capture only the pages and content your workflow needs, and make sure the destination has room for the output.

Firefox, geckodriver, and headless setup

Selenium controls Firefox through geckodriver, Mozilla’s WebDriver-compatible proxy for Gecko-based browsers. The --headless argument selects Firefox’s headless launch mode; the full-page capture method is a Firefox-specific Selenium API. Consult Mozilla’s geckodriver documentation and its Selenium Firefox setup guidance for the environment you deploy to.

Versions and packaging matter. Mozilla’s support guidance identifies Selenium 3.11 or later as required for geckodriver and recommends checking compatibility for specific Firefox and geckodriver versions. In containers, verify that the Firefox binary and geckodriver paths match the installed packages; Mozilla notes that Linux container and Snap path mismatches can cause setup problems. See Mozilla’s geckodriver support information.

Troubleshooting

Symptom	Likely cause	What to check
AttributeError for save_full_page_screenshot	The driver is not Firefox, or the installed Selenium/API version does not expose the method.	Confirm you created webdriver.Firefox, inspect the installed Selenium version, and consult its Firefox API documentation.
Screenshot method returns False	The output could not be written.	Use a writable absolute path, ensure the directory exists, and use a filename ending in .png.
Firefox fails to start	Firefox or geckodriver is missing, incompatible, or not found at the expected path.	Check the installed browser and driver versions and paths, especially in containers or Snap-based Linux environments.
Only part of the page’s content appears	Content may still be loading or may load only after scrolling.	Wait for a page-specific condition, scroll to trigger lazy loading where needed, and wait for the relevant elements before capture.
The image shows only the visible window	The viewport-only screenshot method was used.	Use save_full_page_screenshot() or another Firefox full-page screenshot API.
The file exists but cannot be opened as expected	The workflow may be using the wrong output method or path.	Use the file API for a PNG file; use the bytes or base64 API only when your application handles those representations explicitly.

Performance, reliability, and cost

With Selenium, your workflow manages browser startup, navigation, waits, capture, file handling, and browser shutdown. Reuse the same browser for multiple sequential captures when appropriate, and always call driver.quit() in a finally block so the browser process is closed even if navigation or capture raises an exception.

Capture time depends on browser startup, the target page, any readiness waits, and page length. The documented method saves a PNG, so file size and subsequent transfer time depend on the page image. This approach has no screenshot API charge, but it does require you to provide and maintain the browser environment and its resources.

Or skip the browser setup

ScreenshotNeo provides a website screenshot API and MCP server for developers. One GET request can return a screenshot or PDF; its API documentation describes the available parameters. For a full-page capture, use the API’s full_page option:

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com \
  -d full_page=true \
  -o shot.webp

Cookie banners are accepted and removed before capture, along with 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 cost nothing, and response headers report the page verdict and billing status. AI agents can use its MCP server tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. See ScreenshotNeo for the service and plans. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Does headless mode change which screenshot method to use?

No. Headless mode controls how Firefox launches. Use the Firefox full-page method when you need the whole document.

Can Selenium’s Firefox method save a full-page JPEG?

The documented full-page Selenium methods return or save PNG output. Convert the PNG with an image-processing library if your workflow specifically needs JPEG.

Will the capture wait until every network request finishes?

No such guarantee is provided by the screenshot method. Wait for the content your use case needs, using conditions appropriate to the page.

Is this method specific to Firefox?

save_full_page_screenshot() is part of Selenium’s Firefox WebDriver API. Do not assume another browser driver’s API has the same method.