How to Capture a Full Webpage with Firefox Headless Screenshot

Short answer: Firefox’s --headless --screenshot startup command saves a screenshot at configured dimensions; the documented command-line options do not establish that it captures the entire document. For a built-in full-page image, open Firefox’s Web Console and run :screenshot --fullpage. For repeatable automation, use Firefox’s Marionette screenshot API with its full-document option, while checking the remote screenshot preference described below.

“Headless” means Firefox runs without a graphical interface. It does not, by itself, mean that a screenshot includes content below the viewport. Mozilla documents full-page capture in DevTools and Marionette separately from the startup screenshot flags. See Mozilla’s Web Console helper reference, remote protocol preferences, and the command-line reference.

1. Choose the Firefox capture method

Method	Whole document?	Best fit
Startup CLI: `--headless --screenshot`	Not established by the documented flags	A simple screenshot with explicit dimensions
Web Console: `:screenshot --fullpage`	Yes, documented	A one-off capture in a Firefox session
DevTools screenshot toolbar	Yes, after enabling the button	A GUI workflow
Marionette automation	Supports full-frame capture	Programmatic browser control

2. Run the headless startup screenshot command

This is a runnable example of Firefox’s documented headless screenshot and size flags. It demonstrates a screenshot with those dimensions; it is not a documented guarantee of full-document capture.

firefox --headless --screenshot /tmp/page.png --window-size 1365,900 https://example.com

Use --window-size width,height to set screenshot dimensions. Increasing the window height changes the requested dimensions, but the command-line reference does not describe that as a full-page switch. Check firefox --help on the target machine because available options can vary by build and platform. If the required artifact must include the entire document, use one of the full-page methods below.

3. Capture the full page from Firefox’s Web Console

Open the page in Firefox and wait for the content you need to appear.
Open the Web Console (for example, with Ctrl+Shift+K on Linux/Windows, or Cmd+Option+K on macOS; shortcuts can depend on platform and configuration).
Run the documented helper command:

:screenshot --fullpage --filename page.png

The helper includes content outside the current window bounds. Mozilla documents --filename, --delay, and --dpr in addition to --fullpage. For example:

:screenshot --fullpage --filename page.png --delay 2 --dpr 1

Use a delay when a page needs a little time before the capture. DPR controls image scaling; a higher device pixel ratio can make the output larger. The helper runs in the DevTools Web Console, not as a Firefox startup argument. The Mozilla helper docs list further options, including clipboard output and --selector for capturing a single element.

4. Use the DevTools screenshot button

If you prefer a button over a console command, open DevTools settings and enable the screenshot button under Available Toolbox Buttons. Mozilla documents that this control can capture the entire page; it saves the image in the browser’s Downloads directory. This is a graphical workflow, so it is not a replacement for a headless startup command. See Mozilla’s screenshot tool documentation.

5. Automate full-page capture with Marionette

Mozilla’s Marionette API supports screenshot capture with a full argument for the complete frame. A concrete client call depends on the Marionette library and protocol version you use; consult the Marionette usage and API documentation for the client’s connection setup and exact method signature. Do not substitute the startup --screenshot command and assume it has the same full-document semantics.

Important preference caveat: Mozilla documents remote.screenshot.use_readback as false by default. If enabled, WebDriver and Marionette screenshots use readback of currently composited pixels, so full-document, clip, and element screenshots return only the viewport. This applies to that remote screenshot path; it should not be generalized to the DevTools helper. See Mozilla’s preference reference.

6. Make the capture representative

Wait for the real page state: a full-page capture can still show placeholders if content has not loaded. Use the DevTools helper’s delay where suitable, or use your automation client’s page-state waits.
Check lazy content: pages may load images or sections only after scrolling. A full-page screenshot’s capture scope does not guarantee every site’s lazy-loaded content has been triggered. If essential content is absent, scroll through the page before capturing or use an approach that explicitly loads it.
Consider very long pages: full-document images can have large pixel dimensions and file sizes. If downstream tools impose image limits, capture sections or reduce DPR where supported.
Use stable conditions: animations, rotating carousels, live data, and sticky elements can make results vary between runs. Wait for the desired state and disable motion or hide unstable elements when your workflow permits.
Mind access and privacy: a browser session may include authenticated or personal page content. Store output accordingly and avoid placing credentials in shared command history or logs.

7. Troubleshoot common problems

Symptom	Likely cause	Fix
Headless screenshot contains only the visible area	The startup screenshot flags set a screenshot size; the documented CLI reference does not promise full-document capture.	Use `:screenshot --fullpage` in the Web Console or Marionette’s full screenshot option.
`:screenshot` is treated as invalid input	The command was entered in the page console or shell instead of Firefox’s Web Console.	Open the Web Console for the tab and run the helper there. It is a DevTools command, not a shell command.
Remote automation returns only the viewport	`remote.screenshot.use_readback` may be enabled.	Check that preference in the Firefox profile used by automation. Mozilla documents that the default is false and that enabling it limits remote captures to composited viewport pixels.
Images or sections are missing	Lazy loading, delayed scripts, or asynchronous content has not completed.	Wait for the relevant content, scroll to trigger lazy loading when needed, then capture again.
Output is unexpectedly large	A full page, large viewport, or high DPR produces many pixels.	Lower DPR where available, reduce dimensions if appropriate, or capture the document in sections.
Firefox rejects a CLI option	Flags differ across builds or platform packaging.	Inspect the local `firefox --help` output and use the options supported by that installation.

8. Performance, reliability, and cost

Firefox’s built-in methods avoid a screenshot-service charge, but you supply and maintain the browser environment. Startup CLI capture is simple for a bounded screenshot; full-page automation adds browser startup, page readiness, and image-size considerations. Reliability depends on the target site’s load behavior and your wait conditions, as well as Firefox’s build and automation configuration. The cited Mozilla references do not provide a universal timing benchmark, so measure the pages and environment you intend to capture.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. Use the API for a one-request capture when managing Firefox and DevTools is unnecessary. See the ScreenshotNeo API docs for configuration and response details.

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

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)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners are accepted like a visitor and more than 60 known consent platforms, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Responses include X-Page-Verdict and X-Billed headers.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan.

FAQ

Does Firefox’s `--headless` flag mean full-page?

No. It runs Firefox without a GUI. Full-document capture is separately documented for the Web Console helper and Marionette.

Can I use `--window-size` to guarantee the whole page?

No such guarantee appears in the cited command-line documentation. It controls screenshot dimensions, not a documented full-document mode.

Can I capture just one element?

The Web Console screenshot helper documents --selector for a CSS selector. Marionette and remote preferences can affect their separate automation capture behavior.

Does the full-page option make lazy content load?

It captures outside the viewport, but that alone does not ensure content that a site loads only after scrolling has appeared. Trigger and wait for that content first when it matters.