How to Capture a Website Screenshot with Chromium on Linux
Capture a website from Linux with Chromium headless, choose a viewport, and use Puppeteer when you need full-page or repeatable screenshots.
Run Chromium in headless mode with --screenshot and the page URL:
chromium --headless --screenshot --window-size=1280,900 https://example.com/Chromium saves screenshot.png in the terminal’s current working directory. The executable may be named chromium, google-chrome, or something else on your Linux system, so use the installed browser’s command name. The output captures the viewport; use Puppeteer for full-page capture and more repeatable automation. See the official Chrome Headless command-line reference and Headless mode guide.
1. Take a screenshot from the Linux terminal
- Open a terminal in the directory where you want the screenshot saved.
- Check which Chromium or Chrome command is installed, if you are unsure. For example, try
chromiumorgoogle-chrome. - Run the command with headless mode, screenshot capture, and the target URL:
chromium --headless --screenshot https://example.com/To set the viewport dimensions explicitly:
chromium --headless --screenshot --window-size=1280,900 https://example.com/After Chromium exits, check the current directory for screenshot.png. The Chrome command-line documentation describes that as the default filename and save location. Use a URL you can access and include its scheme, such as https://.
For a mobile-width layout, choose a narrower viewport, for example:
chromium --headless --screenshot --window-size=412,892 https://example.com/This changes the viewport dimensions. It does not by itself emulate a specific phone, device pixel ratio, or touch behavior.
2. Set the viewport and wait for the page
--window-size=WIDTH,HEIGHT sets the headless window dimensions for the capture workflow documented by Chrome. The dimensions are in pixels. Choose a size that matches the layout you need to inspect: narrower sizes expose responsive layouts, while wider sizes show more desktop content.
For pages that take time to load, set a maximum wait using --timeout, in milliseconds:
chromium --headless --screenshot --window-size=1280,900 --timeout=5000 https://example.com/The timeout is a cap on how long Chromium waits before taking the screenshot; it does not guarantee that JavaScript-driven content, lazy-loaded images, or other asynchronous elements are ready. If the page needs a particular element to appear or a more precise readiness condition, use the Puppeteer approach below.
3. Capture a full page or automate screenshots with Puppeteer
The documented Chromium command-line screenshot workflow covers a screenshot and viewport sizing, but does not document a full-page command-line switch. Puppeteer exposes fullPage: true for capturing beyond the visible viewport, and supports screenshotting a selected element. See the Puppeteer ScreenshotOptions API and its screenshots guide.
Install Puppeteer in a Node.js project:
npm install puppeteerSave this as capture.mjs and run it with node capture.mjs https://example.com/. It launches Chromium, sets a viewport, waits for navigation to reach the networkidle2 condition, saves a full-page PNG, and closes the browser even if capture fails.
import puppeteer from 'puppeteer';
const url = process.argv[2] ?? 'https://example.com/';
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 900 });
await page.goto(url, { waitUntil: 'networkidle2', timeout: 30_000 });
await page.screenshot({ path: 'full-page.png', fullPage: true });
} finally {
await browser.close();
}For a visible-viewport image, omit fullPage: true or set it to false. To capture one element, wait for it and use its element handle:
const element = await page.waitForSelector('main article', { timeout: 10_000 });
if (!element) throw new Error('Target element was not found');
await element.screenshot({ path: 'article.png' });Place this snippet after page.goto() inside the try block. Replace main article with a CSS selector present on the target page. Puppeteer’s navigation wait conditions help coordinate capture, but sites with ongoing requests or delayed content may need a different condition or an explicit wait for the content you need.
4. Choose between Chromium CLI and Puppeteer
| Need | Use | Why |
|---|---|---|
| One quick screenshot | Chromium CLI | One command, no script required. |
| Specific viewport dimensions | Either | The CLI has --window-size; Puppeteer sets the viewport in code. |
| Full-page image | Puppeteer | Its screenshot options include fullPage: true. |
| Capture a particular element | Puppeteer | Its element handle supports screenshots. |
| Repeated captures with scripted readiness logic | Puppeteer | Navigation and page interactions can be part of the same script. |
5. Troubleshoot common problems
| Symptom | Likely cause | What to do |
|---|---|---|
chromium: command not found |
The executable has another name or is not available on PATH. |
Try the browser command installed on the machine, such as google-chrome. Distribution-specific installation steps depend on the Linux distribution and were not established by the sources here. |
| No screenshot in the directory you expected | The CLI writes screenshot.png to the current working directory. |
Check the directory from which you launched the command. Run the terminal from the desired output directory before capturing. |
| Screenshot shows an incomplete or blank-looking page | The page may still be loading, require JavaScript, or delay content asynchronously. | Try a suitable --timeout for the CLI. For targeted readiness, use Puppeteer and wait for the relevant selector or page state. |
| Only the top portion of a long page is present | The CLI workflow shown captures the viewport, and its reference does not document a full-page switch. | Use Puppeteer with fullPage: true. |
| Script times out during navigation | The page may not reach the chosen navigation condition within the timeout, including when it keeps network activity open. | Choose an appropriate Puppeteer waitUntil condition or wait for a specific selector, and set a timeout suitable for the page. |
| Element screenshot fails or captures nothing useful | The selector may not match, or the element may not be ready or visible. | Check the selector against the page and wait for it with page.waitForSelector() before calling element.screenshot(). |
6. Performance, reliability, and cost
The CLI is the lightest workflow to operate for an occasional screenshot because it needs only a command. Puppeteer adds a Node.js project dependency and browser-launch code, but makes viewport settings, waits, full-page capture, and repeated steps explicit. Neither a fixed CLI timeout nor a navigation wait condition proves that every dynamic element has finished rendering; wait for the actual content your task depends on.
For repeatable runs, use the same browser setup, viewport, URL, and readiness condition, and ensure the browser is closed after each job. Network errors, access restrictions, bot checks, and changes to the target page can affect output. Screenshot capture is local browser work, so account for the browser runtime and the machine resources needed by your workload. The sources provide no benchmark or universal timing setting.
The Chromium CLI and Puppeteer themselves do not add a per-screenshot service charge, though you supply and maintain the Linux environment and browser installation. If you need a hosted screenshot API, ScreenshotNeo has a free plan with 1,000 shots per month and paid plans starting at $5 for 3,000 shots; see ScreenshotNeo for the service details.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. A single GET request returns an image or PDF, and the API accepts parameter names used by other screenshot APIs to make switching straightforward. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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 and consent notices are accepted like a visitor would, and 60+ known consent platforms, newsletter popups, and chat widgets are removed before capture. Each step can be turned off.
- Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing. Response headers identify the page verdict and whether the shot was billed.
- An MCP server gives AI agents tools for screenshots, page information, and PDF capture.
- 1,000 shots per month are free with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
FAQ
Can I choose the screenshot filename with the Chromium CLI command shown here?
The documented behavior described here saves the default screenshot.png in the current working directory. This guide does not rely on an undocumented filename option.
Does a 412×892 viewport make Chromium emulate a phone?
No. It sets the viewport dimensions. Device emulation involves additional browser settings and is not part of the CLI procedure above.
Which Puppeteer wait condition should I use?
Use a condition that fits the site and the content you need. The example uses networkidle2; if the page continues making requests, wait for a specific selector or another relevant page state instead.
Can Puppeteer save a screenshot of just one component?
Yes. Find the component with a CSS selector and call screenshot() on the returned element handle.
