pageres
Capture website screenshots with specified resolutions
TLDR
Take multiple screenshots of multiple URLs at different resolutions
Provide specific options for a URL, overriding global options
Provide a custom filename template
Capture a specific element on a page
Hide a specific element
Capture a screenshot of a local file
SYNOPSIS
pageres [options] url [url...]
pageres [options] url [width] [height]
PARAMETERS
-h, --help
Displays help information and exits.
-v, --version
Shows the current version of pageres and exits.
url
The URL of the web page to screenshot. Multiple URLs can be provided.
width [height]
The dimensions for the screenshot. width is required, height is optional. If only width is provided, height defaults to width or the page's actual height if --full-page is used. Can also be specified as --size=1024x768 or --size=1024.
--size=widthxheight
Sets the screenshot dimensions. Examples: 1024x768, 1280x* (maintain aspect ratio), 1024 (square).
--full-page
Captures a screenshot of the entire scrollable page, not just the viewport.
--crop=x,y,width,height
Crops the screenshot to the specified region. Values are in pixels relative to the viewport.
--dest=directory
Specifies the destination directory where screenshots will be saved. Defaults to the current working directory.
--format=format
Sets the output image format. Supported values include png and jpg (or jpeg).
--quality=percentage
Sets the quality for JPEG images (0-100). Higher values result in larger file sizes. Ignored for PNG.
--filename=pattern
Defines the naming pattern for output files. Supported variables include <%= url %>, <%= size %>, <%= format %>, <%= date %>, <%= time %>, <%= index %>.
--delay=seconds
Waits for a specified number of seconds before taking the screenshot. Useful for pages with animations or asynchronously loaded content.
--timeout=seconds
Sets a timeout for page loading in seconds. If the page doesn't load within this time, an error is thrown.
--user-agent=string
Sets a custom User-Agent string for the browser. Useful for mimicking different devices or browsers.
--cookie=name=value
Adds a custom cookie to the browser session. Can be specified multiple times.
--header=name=value
Adds a custom HTTP header to the request. Can be specified multiple times.
--javascript=file
Injects a custom JavaScript file that executes after the page loads. Can be specified multiple times.
--css=file
Injects a custom CSS file into the page. Can be specified multiple times.
--selector=CSS_selector
Takes a screenshot of a specific DOM element matched by the CSS selector, instead of the entire page.
--dark-mode
Emulates dark mode preference for the web page, if supported by the site's CSS.
--scale=factor
Sets the device scale factor (e.g., 2 for HiDPI/Retina screens). Defaults to 1.
--no-javascript
Disables JavaScript execution on the target page.
--hide=CSS_selector
Hides elements matching the CSS selector before taking the screenshot. Can be specified multiple times.
--transparent
Makes the background of the screenshot transparent (PNG format only).
--incremental
Appends an incremental index to the filename (e.g., screenshot-0.png, screenshot-1.png).
--ignore-https-errors
Ignores HTTPS certificate errors during navigation.
--username=username
Username for HTTP basic authentication.
--password=password
Password for HTTP basic authentication.
DESCRIPTION
pageres is a powerful command-line interface (CLI) tool designed to effortlessly capture screenshots of web pages. Built on Node.js, it leverages headless browser technology (such as Puppeteer with Chromium) to render web content and then capture it as an image. This makes it ideal for automated tasks like visual regression testing, archiving web pages, generating thumbnails, or simply getting a quick snapshot of a site without a graphical browser. It supports various output formats (PNG, JPG), custom resolutions, full-page screenshots, element-specific captures, and advanced features like custom headers, cookies, JavaScript injection, and dark mode emulation, providing great flexibility for web developers and system administrators alike.
CAVEATS
pageres requires Node.js and a working internet connection to fetch web pages. It downloads and uses a Chromium browser instance via Puppeteer, which can consume significant disk space and memory, especially when capturing many screenshots concurrently or at high resolutions. Complex, highly interactive web pages might require careful tuning of --delay or custom JavaScript injection to ensure all content is rendered before capture. Network issues or heavily protected sites (e.g., with strong CAPTCHAs or bot detection) may hinder its operation.
INSTALLATION
pageres is typically installed globally using npm (Node Package Manager).
npm install --global pageres-cli
Ensure you have Node.js and npm installed on your system before attempting installation.
USAGE EXAMPLES
Capture a basic screenshot of example.com at 1024x768 resolution:
pageres example.com 1024x768
Screenshot multiple URLs and sizes, saving them to a 'screenshots' directory:
pageres google.com twitter.com 1280x800 800x600 --dest=screenshots
Capture the full page of a specific element:
pageres wikipedia.org --full-page --selector='.mw-parser-output'
Add a 5-second delay before capturing:
pageres myanimatedsite.com --delay=5
Save as a JPEG with 80% quality:
pageres github.com 1024x768 --format=jpg --quality=80
HISTORY
pageres was created by Sindre Sorhus, a prolific Node.js developer known for many popular open-source packages. It emerged as a solution for programmatic web screenshotting in the Node.js ecosystem. Initially, it might have relied on libraries like PhantomJS, but it later transitioned to using Puppeteer, which provides a high-level API to control headless Chrome or Chromium. This shift greatly improved its performance, reliability, and modern web compatibility, making it a staple tool for web automation and development tasks since its inception.
SEE ALSO
wget(1), curl(1), wkhtmltopdf(1), convert(1) (ImageMagick), screencapture(1) (macOS)