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

Short answer: Firefox supports command-line screenshots in headless mode, but Mozilla’s current command-line reference does not document a full-page flag for that command. You can set the screenshot dimensions with --window-size, but that is not documented as capturing the entire document. For a documented capture of content beyond the viewport, Mozilla provides the Web Console helper :screenshot ... --fullpage; the reviewed documentation does not establish that this helper can be invoked in a headless-only session.

1. Take a headless screenshot from the command line

Use Firefox’s CLI when a screenshot at a specified width and height is enough. The --screenshot switch implies headless mode, so the explicit --headless flag is optional, though including it makes the intent clear.

firefox --headless --screenshot /absolute/path/page.png --window-size=1440,1000 https://example.com/

This saves a screenshot at the selected dimensions. A taller window can show more vertical content, but do not treat it as a documented whole-document capture. Check your installed build’s available options with firefox --help; options can vary by build and platform. See Mozilla’s command-line reference and its headless mode overview.

Choose an output path and size

• --screenshot /absolute/path/page.png writes to the given path. If no path is supplied, Firefox saves in the working directory.
• --window-size=1440,1000 sets screenshot width and height in pixels. Use a comma between the values.
• Use an absolute path in automated jobs to avoid uncertainty about the process working directory.
• Choose PNG when you want a lossless output format, and ensure the destination directory exists and is writable.

The CLI reference documents --headless, --screenshot, and --window-size; it does not list a CLI --fullpage option. Do not infer a full-page guarantee from a large height.

2. Use Firefox’s documented full-page capture helper

For the entire webpage, including content outside the current window bounds, Mozilla documents the DevTools Web Console helper:

:screenshot /absolute/path/page.png --fullpage

This runs in Firefox’s Web Console, not as a documented headless command-line flag. The reviewed Mozilla documentation does not establish a headless-only way to run this console helper. If your requirement is both unattended headless execution and a guaranteed full-document screenshot, the sources here do not provide a documented built-in CLI route.

Documented helper options

Option	What it does	When to use it
--fullpage	Includes webpage portions outside the current window bounds.	Capturing the whole document from the Web Console.
--delay	Waits the specified number of seconds before capture; fractional seconds are supported.	Allowing a known animation or delayed content to settle.
--dpr	Sets the device pixel ratio for the capture.	Adjusting output pixel density.
--filename	Specifies a PNG filename.	Choosing or scripting the destination filename.
--selector	Captures a CSS-selected element and its descendants.	Capturing a specific component rather than the page.

For exact helper syntax and behavior, see Mozilla’s Web Console helpers and screenshot guide. Capturing again to a filename that already exists overwrites that image, so use unique names or move old captures if you need to keep them.

3. Handle dynamic pages and repeatable captures

A full-page command describes capture extent, not whether every image or script-driven section has finished loading. Readiness depends on the site. Mozilla’s helper supports a delay, but its documentation does not promise that a particular delay will load every lazy image, animation, or asynchronous component.

1. Open the target page and confirm the content you need is present.
2. If content appears after a known delay, use the helper’s --delay option and allow enough time for that content to render.
3. For unattended CLI screenshots, use a controlled test page or another readiness check in your surrounding workflow; the documented CLI flags do not provide a page-specific readiness guarantee.
4. Save each run under a unique filename if previous screenshots must be preserved.
5. Compare the output dimensions and page content after changes to Firefox or the target site.

Do not assume that a single delay works for every page. Network speed, client-side rendering, consent dialogs, and content triggered by scrolling can all affect what is visible at capture time.

4. Troubleshooting

Symptom	Likely cause	What to try
The CLI screenshot shows only a viewport-sized area.	--window-size sets screenshot dimensions; Mozilla does not document it as full-document capture.	Use the Web Console :screenshot ... --fullpage helper for the documented full-page path, or choose a capture workflow that explicitly supports full-page headless capture.
--fullpage is rejected by Firefox CLI.	The reviewed CLI reference does not list this as a command-line flag; it belongs to the Web Console helper syntax.	Run the helper in the Web Console rather than adding it to the CLI command.
The output is missing content that appears later.	The page had not rendered that content when capture occurred, or it loads only after interaction or scrolling.	Wait for the content before capture; the Web Console helper’s documented --delay can handle a known delay but is not a universal readiness check.
The screenshot was saved somewhere unexpected.	A relative path is resolved from the process working directory, or no path was given.	Specify an absolute output path and verify its parent directory exists.
A previous image disappeared.	The capture reused an existing filename and overwrote it.	Use a unique filename for each run or archive the old image first.
Firefox hangs during a Linux headless run.	A Mozilla Support thread reports one Firefox 125-era Linux hang; it is anecdotal and does not establish a general cause.	Check your local build and environment. In that thread, a moderator suggested trying a dedicated profile; treat it as a troubleshooting lead, not a guaranteed fix. See the support discussion.
A documented option is unavailable.	Available CLI options can differ by platform or build.	Run firefox --help on the machine that will capture the page.

5. Performance, reliability, and cost

The command-line route is a direct browser invocation and works well for shell workflows when fixed screenshot dimensions meet the requirement. A larger requested image can mean more output pixels and a larger file, but the cited Mozilla material provides no performance benchmarks. Measure your own target pages and execution environment if runtime or memory use matters.

For reliability, pin down the Firefox build and operating environment in automation, use explicit paths, and confirm page readiness before capture. A screenshot operation cannot guarantee that third-party content, lazy images, or dynamic application state has settled. Repeated captures to the same output path overwrite the prior file.

Firefox is available as browser software; these documented capture paths do not introduce a per-screenshot service charge. Your actual costs may come from the machine or infrastructure running Firefox. The sources reviewed provide no benchmark or cost comparison against hosted screenshot services.

6. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF, and its options include full-page capture. The API parameters other screenshot APIs use also work. See the ScreenshotNeo API documentation for configuration and response details.

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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Replace YOUR_API_KEY with your key. The Python example requires requests. The Node.js example uses fetch and Bun’s file writer to save the response; with Node.js, write the response bytes using fs. Request the output format you need according to the API documentation.

Before the capture, ScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each of these steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page info, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for free and get 1,000 screenshots a month with no card.

7. FAQ

Does a tall --window-size guarantee a whole-page image?

No. It sets screenshot dimensions. Mozilla’s CLI reference does not describe it as a full-document capture option.

Can I use :screenshot --fullpage in a headless-only session?

The reviewed Mozilla documentation describes the helper for the Web Console and does not establish a headless-only invocation method.

Can the Web Console helper capture one element?

Yes. Mozilla documents --selector for capturing one CSS-selected element and its descendants.

Will Firefox wait for lazy-loaded images automatically?

The cited documentation does not promise that. Make sure the page is ready before capture; a delay only helps when you know how long the page needs.