Convert a Local HTML File to PNG Using Chrome Headless

Use Chrome’s --headless and --screenshot flags with a file:/// URL for the HTML file. For example: "/path/to/chrome" --headless --screenshot=/path/to/output.png --window-size=1280,800 "file:///absolute/path/to/page.html". Replace the executable and file paths with paths for your system. Chrome documents the screenshot flags and output behavior; using a local file URL is a practical invocation, so verify the result on your machine.

Run Chrome Headless on a local HTML file

First locate the Chrome executable installed on your system. The command name and executable path vary by operating system and installation. Google’s Chrome Headless mode guide shows platform-specific invocation examples.

#	Preview	Product	Price
1		ASUS CHROMEBOX 3-N017U Mini PC with Intel Celeron, 4K UHD Graphics and Power Over Type C Port, Star...	$169.98	Buy on Amazon

As an Amazon Associate I earn from qualifying purchases.

1. Use an absolute path to the Chrome executable. Quote it if any part of the path contains spaces.
2. Pass the headless and screenshot flags. Add an explicit output filename and viewport size if you want to control them.
3. Provide the HTML file as a file URL. Use an absolute path after file:///; quote the complete URL. Encode special characters in the URL as needed.
4. Run the command and inspect the PNG. If the page has not finished rendering when captured, adjust the timing flags described below.

Example command:

"/path/to/chrome" --headless --screenshot=/path/to/output.png --window-size=1280,800 "file:///absolute/path/to/page.html"

The Chrome Headless documentation demonstrates target-page URLs and screenshot flags, but does not give this exact local-file example. Treat file:/// as a practical form to try rather than a platform-specific official recipe. File URL encoding and executable paths can differ between systems.

Choose the output file and viewport

Set the PNG path

Without an explicit output path, Chrome saves the screenshot as screenshot.png in the current working directory. The Chrome for Developers Headless command-line reference documents this default. To choose another filename or location, set --screenshot to that path, such as --screenshot=/path/to/output.png. Use a .png filename for this task.

#1 Best Overall

ASUS CHROMEBOX 3-N017U Mini PC with Intel Celeron, 4K UHD Graphics and Power Over Type C Port, Star Gray (Renewed)

• Processor and Memory Configuration: Features an Intel Celeron 3865U Processor with 4GB DDR4 Memory, Gigabit LAN, 802.11ac Wi-Fi and 32GB M.2 SATA SSD
• Android App Compatibility: Full support of Android apps from Google play on Chrome OS
• 4K UHD Graphics Display Support: Integrated Intel 4K UHD Graphics supports 2x monitors using HDMI and DisplayPort over Type C for compatibility with legacy Display connections like VGA and DVI
• Wireless Connectivity and File Sharing: Share files or stream your favorite media with Intel 802.11ac Wi-Fi, Bluetooth 4.2, and USB 3.1 Gen 1 Type a & Type C Ports
• Power Over Type C Technology: Power over Type C minimizes cable clutter and delivers power to monitors, projectors, and mobile devices

$169.98

Buy on Amazon

Set the viewport dimensions

Add --window-size=WIDTH,HEIGHT to specify the viewport, for example --window-size=1280,800. The dimensions describe the browser viewport; they do not by themselves guarantee that the entire page, including content below the viewport, appears in the image. Check the output to confirm it captures the portion you need.

Wait for pages that render slowly or use timers

Chrome’s --timeout sets the maximum wait before capture, including when loading has not finished. Use it when the page needs more time to load. The --virtual-time-budget flag instead fast-forwards timer-based code, which can help when page behavior depends on timers. These flags solve different timing issues and do not guarantee that every font, image, script, or animation has reached the desired state. Test the result and adjust the capture setup for the page.

Troubleshoot missing or unexpected output

• The command cannot find Chrome: Check the executable path and use the invocation appropriate for your operating system. Quote paths that contain spaces.
• The local page does not open: Confirm the HTML file exists and that the URL uses an absolute path after file:///. Quote the URL and encode spaces or other special characters if necessary.
• The PNG is in an unexpected location: Chrome’s default is screenshot.png in the current working directory. Specify a full path with --screenshot to control where it is saved.
• The image is clipped or the size is wrong: Set --window-size=WIDTH,HEIGHT for the intended viewport and inspect whether the capture includes the content you need.
• Images, fonts, or scripts are missing: The page may not have finished rendering before capture. Try an appropriate --timeout, then inspect again; it sets a maximum wait, not proof that every page asset has settled.
• Timer-driven content looks different: Consider --virtual-time-budget for code driven by timers. It fast-forwards timer-based execution and is not interchangeable with a maximum wait.

Or skip the browser setup

ScreenshotNeo can capture a URL with one API request. It is designed for web pages, so for a local HTML file you would first need to make the page reachable at a URL.

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

See the ScreenshotNeo API documentation for request options. ScreenshotNeo removes cookie banners, newsletter popups and chat widgets before the shot; bot checks, blank pages and failed loads are never billed. Its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for ScreenshotNeo.

Frequently Asked Questions

How do I set the screenshot size in Chrome Headless?

Use --window-size=WIDTH,HEIGHT, such as --window-size=1280,800. This sets the viewport dimensions, not a guarantee of a full-page capture.

Where does Chrome save the screenshot by default?

It saves screenshot.png in the current working directory. Set an explicit path with --screenshot=/path/to/output.png to choose another location.

Quick Recap

Bestseller No. 1

ASUS CHROMEBOX 3-N017U Mini PC with Intel Celeron, 4K UHD Graphics and Power Over Type C Port, Star Gray (Renewed)

Android App Compatibility: Full support of Android apps from Google play on Chrome OS

$169.98

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.