What is url-to-png?

URL to PNG is a self-hosted HTTP service that renders webpage screenshots as PNG images. It uses Playwright (Chromium) for parallel rendering and accepts query parameters to customize output dimensions, viewport size, mobile emulation, dark mode, full-page capture, and device scale factor. Generated images can be cached using a choice of storage backends: local filesystem, S3-compatible object storage, or CouchDB. The service exposes a Prometheus metrics endpoint for monitoring the browser connection pool. It runs as a Docker container (ghcr.io/jasonraimondi/url-to-png) on port 3089, or locally via pnpm with Playwright Chromium installed. Configuration is done through environment variables for logging, cache control, allow/block lists, Playwright timeouts, connection pool sizing, defaults for all rendering options, encryption, and storage provider settings. The project is licensed under MIT and actively maintained.

Should you self-host url-to-png?

url-to-png scores 49/100 on selfhost.directory (how scoring works) and ranks #13 of 16 in Web Scraping. It has 256 GitHub stars.

It shipped 2 stable releases in the past year. The latest, v2.1.4, came out on 18 April 2026.

Setup is easy: most people get it running in one sitting. An official Docker image is available. It is MIT-licensed and written mostly in Typescript.

Its closest alternative on selfhost.directory is firecrawl (91/100, 196 246 stars). It scores higher overall, so compare the two before you pick. See url-to-png vs firecrawl side by side.

Features

Allow/block list for domains
Browser connection pooling
Configurable Playwright options
Customizable image dimensions
Device scale factor support
Force reload bypassing cache
Full-page screenshot capture
Image caching with multiple storage backends
Mobile user agent emulation
Prometheus metrics endpoint
Request encryption
URL to PNG screenshot generation

How to configure url-to-png

ALLOW_LISTComma-separated list of allowed domains for screenshots
Comma-separated list of allowed domains for screenshots
AWS_ACCESS_KEY_IDAWS access key ID
AWS access key ID
AWS_BUCKETName of the S3 bucket to store images
Name of the S3 bucket to store images
AWS_DEFAULT_REGIONus-east-1AWS region for S3
AWS region for S3
AWS_ENDPOINT_URL_S3Endpoint URL for S3 (optional)
Endpoint URL for S3 (optional)
AWS_FORCE_PATH_STYLEfalseUse path-style URLs for S3
Use path-style URLs for S3
values: true, false
AWS_SECRET_ACCESS_KEYAWS secret access key
AWS secret access key
BLOCK_LISTComma-separated list of restricted domains for screenshots
Comma-separated list of restricted domains for screenshots
BROWSER_TIMEOUT10000Browser timeout in milliseconds for rendering
Browser timeout in milliseconds for rendering
BROWSER_WAIT_UNTILdomcontentloadedEvent to wait for before considering the page loaded
Event to wait for before considering the page loaded
values: load, domcontentloaded, networkidle
CACHE_CONTROLpublic, max-age=86400, immutableCache-Control header value for the responses
Cache-Control header value for the responses
COUCHDB_DATABASEimagesName of the CouchDB database to store images
Name of the CouchDB database to store images
COUCH_DB_HOSTCouchDB host
CouchDB host
COUCH_DB_PASSCouchDB password
CouchDB password
COUCH_DB_PORTCouchDB port
CouchDB port
COUCH_DB_PROTOCOLProtocol for connecting to CouchDB (http or https)
Protocol for connecting to CouchDB (http or https)
values: http, https
COUCH_DB_USERCouchDB username
CouchDB username
CRYPTO_KEYEncryption key for sensitive data (JWK format)
Encryption key for sensitive data (JWK format)
DEFAULT_DEVICE_SCALE_FACTOR1Default device scale factor (e.g., 2 for retina displays)
Default device scale factor (e.g., 2 for retina displays)
DEFAULT_HEIGHT250Default height of the rendered image in pixels
Default height of the rendered image in pixels
DEFAULT_IS_DARK_MODEfalseWhether to request dark mode
Whether to request dark mode
values: true, false
DEFAULT_IS_FULL_PAGEfalseWhether to capture the full page or clip at viewport height
Whether to capture the full page or clip at viewport height
values: true, false
DEFAULT_IS_MOBILEfalseWhether to emulate a mobile device
Whether to emulate a mobile device
values: true, false
DEFAULT_VIEWPORT_HEIGHT1080Default height of the browser viewport in pixels
Default height of the browser viewport in pixels
DEFAULT_VIEWPORT_WIDTH1080Default width of the browser viewport in pixels
Default width of the browser viewport in pixels
DEFAULT_WIDTH250Default width of the rendered image in pixels
Default width of the rendered image in pixels
IMAGE_STORAGE_PATHDirectory path where images will be stored (filesystem provider)
Directory path where images will be stored (filesystem provider)
LOG_LEVELdebugLogging level (debug, info, warn, error)
Logging level (debug, info, warn, error)
values: debug, info, warn, error
METRICSfalseEnable or disable metrics collection
Enable or disable metrics collection
values: true, false
NODE_ENVdevelopmentNode environment
Node environment
values: development, production
POOL_IDLE_TIMEOUT_MS15000Idle timeout for browser connection pool in milliseconds
Idle timeout for browser connection pool in milliseconds
POOL_MAX10Maximum number of connections in the browser pool
Maximum number of connections in the browser pool
POOL_MAX_WAITING_CLIENTS50Maximum number of waiting clients for the browser pool
Maximum number of waiting clients for the browser pool
POOL_MIN2Minimum number of connections in the browser pool
Minimum number of connections in the browser pool
PORT3089Port number for the application to listen on
Port number for the application to listen on
STORAGE_PROVIDERstubStorage provider for caching rendered images
Storage provider for caching rendered images
values: stub, filesystem, s3, couchdb