How to Install Chrome Headless on Ubuntu for Website Screenshots

To take a website screenshot with headless Chrome on Ubuntu, install Google Chrome’s Stable .deb package, then run google-chrome --headless --screenshot --window-size=1365,900 https://example.com/. Chrome writes screenshot.png to the current working directory. Headless mode runs Chrome without a visible browser window; current Chrome uses the regular Chrome binary for this mode. See the Chrome Headless documentation and CLI reference.

1. Check Ubuntu and system architecture

Google Chrome is distributed as a .deb package rather than from the standard Ubuntu repositories. Check the machine’s architecture before downloading a package:

lsb_release -a
dpkg --print-architecture

The architecture command commonly prints amd64 for 64-bit x86 systems. Package availability can vary by architecture and release; use a package published for your machine. Google’s direct Stable download URL and the install steps below use the architecture suffix returned by dpkg, as documented in the installation guide for Ubuntu. If the URL does not resolve for your architecture, check Google’s current package availability instead of installing a mismatched build. See the Ubuntu Chrome installation guide.

2. Install Google Chrome Stable

Download the matching package and install it with apt, which resolves package dependencies:

arch=$(dpkg --print-architecture)
wget "https://dl.google.com/linux/direct/google-chrome-stable_current_${arch}.deb"
sudo apt install "./google-chrome-stable_current_${arch}.deb"

The command uses a local package file, so keep the ./ prefix in the apt install argument. The package can configure Google’s APT repository so subsequent Chrome updates are available through Ubuntu’s package workflow. Update package metadata and installed packages with:

sudo apt update
sudo apt upgrade

Confirm the executable name and installed version:

command -v google-chrome || command -v google-chrome-stable
 google-chrome --version

If the first command finds google-chrome-stable instead, use that name in the screenshot command. Remove the accidental leading space before google-chrome if copying the version command as a standalone shell line:

google-chrome --version

3. Capture a website screenshot

Run Chrome from a terminal with a URL and a viewport size:

google-chrome --headless --screenshot --window-size=1365,900 https://example.com/

Find the resulting file in the directory where the command ran:

pwd
ls -lh screenshot.png
file screenshot.png

--screenshot saves screenshot.png in the current working directory by default. --window-size=WIDTH,HEIGHT sets the viewport dimensions in pixels. For example, use 412,892 to render at a narrow mobile viewport. The basic CLI screenshot is generally a viewport capture; do not assume it will stitch an arbitrarily long page into a full-page image. These behaviors are described in the official CLI reference.

When you need to control the output location, change into the target directory before launching Chrome:

mkdir -p captures
cd captures
google-chrome --headless --screenshot --window-size=1365,900 https://example.com/

The supported CLI example names the output screenshot.png. If a workflow requires a particular output filename or more detailed capture control, use a browser automation library or a screenshot API that exposes those controls.

4. Useful Headless CLI options

Option	What it does	Example
`--headless`	Runs Chrome without visible UI.	`--headless`
`--screenshot`	Captures a screenshot to `screenshot.png` in the current directory.	`--screenshot`
`--window-size=W,H`	Sets viewport dimensions.	`--window-size=1365,900`
`--timeout=MS`	Sets the maximum wait before capture, even if the page is still loading.	`--timeout=5000`
`--virtual-time-budget=MS`	Advances browser virtual time for time-dependent page scripts.	`--virtual-time-budget=5000`
`--dump-dom`	Prints the serialized DOM after scripts have run; useful for diagnosing rendering or page content.	`--dump-dom https://example.com/`
`--print-to-pdf`	Creates `output.pdf` in the current directory.	`--print-to-pdf https://example.com/`

A combined capture command with a bounded wait is:

google-chrome --headless --screenshot --window-size=1365,900 --timeout=10000 https://example.com/

--timeout is a maximum wait, not a guarantee that every image, font, animation, or application request has completed. The CLI reference says capture occurs when the specified maximum is reached even if the page remains loading. Virtual time can help when scripts rely on timers; it does not ensure that remote services have responded.

To inspect the DOM after JavaScript has modified it, use --dump-dom. To generate a PDF instead of an image, use --print-to-pdf. These are separate output modes; they do not change the screenshot’s viewport behavior.

5. Current Headless Chrome versus Headless Shell

For ordinary website screenshots, run the installed Chrome binary with --headless. Modern Headless is a mode of Chrome itself, so it shares Chrome’s browser implementation. The Chrome documentation describes it as running Chrome in an unattended environment without visible UI.

Older tutorials may refer to the original “old Headless” implementation. Starting with Chrome 132, that implementation is no longer part of the Chrome binary; workflows that specifically require it need the separate chrome-headless-shell binary. Chromium’s project documentation notes that precompiled shell binaries are distributed through Chrome for Testing. Do not add the shell just to take a normal screenshot; use it only when an existing workflow explicitly depends on its behavior. See the Chromium Headless README.

6. Automate a repeatable capture

For a one-off screenshot, the CLI is enough. For repeatable jobs, use a script that sets the working directory, records failures, and gives each capture a predictable path. This Bash example accepts a URL and optional output directory, and avoids overwriting an existing screenshot by adding a timestamp:

#!/usr/bin/env bash
set -euo pipefail

url="${1:?Usage: capture.sh URL [OUTPUT_DIR]}"
out_dir="${2:-captures}"
mkdir -p "$out_dir"
output="$out_dir/screenshot-$(date -u +%Y%m%dT%H%M%SZ).png"

chrome_bin="$(command -v google-chrome || command -v google-chrome-stable)"
"$chrome_bin" --headless --screenshot="$output" \
  --window-size=1365,900 --timeout=10000 "$url"

if [[ ! -s "$output" ]]; then
  echo "Screenshot missing or empty: $output" >&2
  exit 1
fi
printf 'Saved %s\n' "$output"

Save it as capture.sh, make it executable with chmod +x capture.sh, then run ./capture.sh https://example.com/. The command-line output-path syntax can vary with Chrome builds; if your binary does not accept --screenshot=PATH, use the documented default filename and move it after capture, or change into the output directory first.

7. Performance, reliability, and cost considerations

Wait only as long as the page needs. A larger timeout can help slow pages but increases job duration. A short timeout can produce a screenshot before client-rendered content or remote assets appear.
Keep viewport dimensions consistent. Different widths can trigger responsive layouts, change line wrapping, and alter what is visible.
Account for page variability. Animations, personalized content, consent dialogs, network timing, and bot checks can change captures. A timeout only bounds the wait; it does not make a page deterministic.
Run with the right permissions. Avoid running a browser as root where possible. Server and container environments may need compatible system libraries and fonts installed for the browser package and the pages being captured.
Plan for browser updates. The Chrome package can receive updates via APT. Changes in browser versions may alter rendering, so pin or record the version when repeatability matters.
Direct cost. Chrome is software you install on your Ubuntu machine; this method does not charge per screenshot. Your server, compute, bandwidth, and maintenance still have costs.

8. Troubleshooting

Symptom	Likely cause	What to do
`google-chrome: command not found`	Chrome is not installed or the package exposes a different executable name.	Check `command -v google-chrome-stable`, then use the executable found. If neither exists, rerun the install and inspect its output.
Download returns 404 or package has wrong architecture	The direct package URL does not offer a build for the machine architecture.	Check `dpkg --print-architecture` and verify current Google package availability for that architecture. Do not force-install an incompatible package.
APT reports unmet dependencies	Package metadata or dependencies are incomplete.	Run `sudo apt update`, then `sudo apt --fix-broken install`, and retry `sudo apt install ./google-chrome-stable_current_ARCH.deb` with the actual filename.
Chrome starts but no screenshot appears	The command ran in a different working directory, the process failed, or a non-default output path was specified.	Check `pwd`, inspect terminal errors and exit status, then search the expected directory for `screenshot.png`.
The screenshot is blank or missing page content	The page had not rendered before capture, blocked the request, failed to load, or needs client-side data.	Try a longer `--timeout`, inspect `--dump-dom`, verify the URL is reachable from the Ubuntu host, and check whether the page requires authentication or rejects automated traffic.
Images or fonts are absent	Remote assets loaded slowly, were blocked, or use fonts unavailable to the host.	Increase the wait, confirm network access from the server, and install the required system fonts if the page depends on them.
CLI exits too early on an app with delayed rendering	Page completion is not synchronized with the site’s application state.	Increase the timeout or use browser automation that waits for a page-specific selector or condition. A fixed delay is less reliable than waiting for the content you need.
Old tutorial says to use `--headless=old`	The tutorial targets the retired built-in old Headless mode.	Use current `--headless` for normal captures. For a workflow that specifically requires old Headless, obtain the standalone `chrome-headless-shell` through Chrome for Testing.

Or skip the browser setup

If you need screenshots without installing and maintaining Chrome on an Ubuntu host, ScreenshotNeo takes a screenshot with one GET request. See the API documentation for options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -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 are not billed, and response headers identify the page verdict and billing status. An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

FAQ

How do I take a screenshot with headless Chrome on Ubuntu?

Run google-chrome --headless --screenshot --window-size=1365,900 https://example.com/. The output is normally screenshot.png in the current directory.

Does Chrome Headless need a desktop session?

No. Headless mode runs without a visible browser UI, which makes it suitable for unattended command-line jobs.

Does `--screenshot` capture the entire page?

The CLI reference documents a screenshot and viewport size, but the basic command should not be treated as a guaranteed full-page capture. Use a browser automation or screenshot API with explicit full-page support if you need the whole document.

Should I install Chromium instead?

This guide installs Google’s Chrome package. Chromium is a separate browser distribution; choose it if your environment requires an open-source browser package or Chrome’s package is unavailable for the machine architecture.

Can I create a PDF with the same command?

Use Chrome’s PDF output mode: google-chrome --headless --print-to-pdf https://example.com/. It creates output.pdf in the current directory.