Short answer: you can run Puppeteer’s official Docker image on an ARM host only when the browser inside the image is compatible with that host. The published image is Debian-based and installs Chrome for Testing, but Google does not publish an official Linux ARM64 Chrome binary. On a Raspberry Pi, Graviton server, or another Linux ARM64 machine, use an ARM64 Chromium image, build an ARM64-specific derivative, or run the x64 image through emulation. Apple silicon macOS is a different case: macOS ARM64 is supported, while Linux ARM64 has the Chrome-binary limitation.
What the official image actually provides
Puppeteer has published Docker support since version 16.0.0. The maintained image is distributed through GitHub Container Registry and is designed to remove the usual container setup work: it starts with Debian’s Node image, installs Puppeteer, installs Chrome for Testing together with its shared-library dependencies, and runs the browser as an unprivileged user.
The current Dockerfile uses node:24-bookworm. It sets locale and DBus environment variables, creates a user named pptruser with UID 10042, installs packages, temporarily switches to root for npx puppeteer browsers install chrome --install-deps, then switches back to the non-root user for runtime. A registry listing currently shows the example tag ghcr.io/puppeteer/puppeteer:25.12.0; tags change, so review and pin a tag or digest before production deployment.
Why an ARM host can still fail
Docker image architecture and browser architecture are separate concerns. An image may be pulled on an ARM64 machine while the browser binary inside it remains x64-only. Puppeteer collaborator OrKoN stated on March 27, 2024 that macOS arm64 is fully supported, but Chrome does not officially support Linux arm64; Linux ARM users therefore need a third-party ARM64 Chromium build or emulation. There is no official native Linux ARM64 Chrome binary to install into the standard image.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
- Powerful Performance: Quad 64-bit 1.2GHz ARM Cortex-A53 Processors, ARM Mali-450 666MHz GPU, 1GB of High Bandwidth DDR4, High Dynamic Range Display Engine for H.265 HEVC, H.264 AVC, VP9 Hardware Decoding
- Energy Efficient: Only 2W power consumption in standard scenarios, built on advanced 28nm High-Performance Mobile (HPM) fabrication technology
- Hardware Extensibility: 40 Pin header enables hardware re-use, maintains RPi compatible alternate pin functions, ultra high speed (UHS) Micro SD card support, onboard IR, ADC header, eMMC module expansion connector
- Latest Software Support: Libre Computer provides Ubuntu 23.04 and 22.04 LTS, Debian 12/Raspbian 11 support with hardware-accelerated video playback and 3D graphics
- Open Software Standard: Libre Computer platforms run standard ARMv8 (64-bit) code from major Linux distributions, pre-compiled open source bootloaders provided for rapid design and deployment
Choose an ARM deployment strategy
| Approach | Native Linux ARM64 browser | What you maintain | When it fits |
|---|---|---|---|
| Official image on a supported architecture | No for Linux ARM64 Chrome; works on supported x64 hosts and the separate macOS ARM64 case | Mostly your Puppeteer code and image pin | You are not depending on native Linux ARM64 Chrome |
| Third-party ARM64 Chromium image | Yes, if the publisher supplies a compatible build | Publisher trust, image updates, and Puppeteer/Chromium matching | You need native performance on a Pi or ARM64 server |
| ARM64-targeted derivative | Yes, when your chosen base includes a compatible Chromium | Dockerfile, browser updates, system libraries, and testing | You need reproducible control over the complete stack |
| x64 image under emulation | No | Emulation configuration and workload testing | Compatibility matters more than throughput or latency |
CanardConfit documents an ARM64 Puppeteer image with Docker Hub, GitHub Container Registry, and Quay distribution options. Treat any third-party image as a software dependency: inspect its Dockerfile, verify its release process, pin a digest, and test the exact Puppeteer and Chromium versions your application uses.
Run the pinned official image
For a host and image combination that can execute the included browser, this smoke test prints the Chrome version and exits. The --init flag adds a tiny init process that reaps child processes; --rm removes the test container after it exits.
docker pull ghcr.io/puppeteer/puppeteer:25.12.0
docker run -i --init --rm --cap-add=SYS_ADMIN
--name puppeteer
ghcr.io/puppeteer/puppeteer:25.12.0
node -e "const puppeteer = require('puppeteer'); puppeteer.launch({headless: true}).then(async b => { console.log(await b.version()); await b.close(); });"The tag above is an example from the current registry listing, not a promise that it will remain current. Resolve the tag or, preferably, a reviewed digest as part of your release process. The extra capability is commonly used by the reference run command during development; apply your organization’s container security policy and test whether your chosen sandbox configuration can run with fewer privileges.
Use a script instead of an inline command
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({
headless: true,
userDataDir: '/tmp/.puppeteer-profile'
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', {waitUntil: 'networkidle2'});
console.log({title: await page.title(), version: await browser.version()});
} finally {
await browser.close();
}
})();Build your application image from the reviewed Puppeteer image or mount the script read-only. Keep the browser profile and cache on writable storage, and run as the image’s pptruser rather than changing the container to root.
Make a native ARM64 image
A native build requires two compatible pieces: an ARM64 base image and an ARM64 Chromium package. Simply adding --platform linux/arm64 to the official image does not create an ARM64 Chrome binary where none is published.
Build with Docker Buildx
- Choose an ARM64 base or a third-party ARM64 Chromium image whose maintenance and version policy you can accept.
- Write a derivative Dockerfile that installs the matching Puppeteer package and the browser’s required shared libraries.
- Create or select a Buildx builder capable of producing ARM64 images. On an x64 workstation this normally requires an emulation-enabled builder; on an ARM64 host the native builder can compile natively.
- Build and test the target platform:
docker buildx build
--platform linux/arm64
-t your-registry/puppeteer-arm64:reviewed
--load .For a registry publication, replace --load with --push. Record the base-image digest, Puppeteer version, Chromium version, and build date in your release metadata. Test navigation, screenshots, PDFs, downloads, JavaScript-heavy pages, and any fonts your production workload requires; “the browser launched” is not enough to establish compatibility.
Version matching matters
Puppeteer is coupled to browser revisions. An ARM64 Chromium supplied by another project may launch but still expose protocol differences, missing codecs, or behavior that your Puppeteer release does not expect. Keep the Puppeteer package and Chromium revision deliberately aligned, and upgrade them together in a staging build.
Rank #2
- Edge2 is equipped with a high-performance SOC - RK3588S, 8nm lithography process, 8-core 64-bit, 2.25GHz Quad core ARM Cortex-A73 and 1.8GHz Quad core Cortex-A55 CPU Integrated with ARM Mali-G610 MP4 quad-core GPU up to 1GHz，Build-in 6 TOPS Performance NPU
- Edge2 uses the AP6275P Wi-Fi 6 PCIe module supports IEEE 802.11 ax/ac/a/b/g/n and 2T2R. This advanced wireless transceiver module makes data transmission stable and fast
- Edge2 supports 8K, 60fps H.265/VP9 video decoding and 8K, 30fps H.265/H.264 video encoding. In addition, up to 32-channels of 1080P, 30fps decoding or 16-channels of 1080P, 30fps encoding can be done simultaneously
- Quad Display Interfaces: x1 HDMI, x1 USB-C, x2 DSI; Edge2's hardware supports up to four independent displays, however in practice the number of independent displays will be limited by the OS.
- Maker Friendly - Multiple FPC connectors for connecting with accessories and extension. x1 30-pin 0.5mm MIPI-DSI Interface, x1 40-pin 0.5mm MIPI-DSI Interface, x3 30-pin 0.5mm MIPI-CSI Interface, x2 30-pin 0.5mm FPC Connector, x1 7-pin Pogo Pad (USB, UART, 5V) Multiple systems（Android, Ubuntu and many other operating systems）can be installed in a few steps with the built-in OOWOW, easy and fast
Run x64 through emulation
Emulation follows the maintainer’s stated workaround: run the x64 official image on an ARM64 host using the host’s x64 emulation support. This avoids finding a native browser, but adds an architecture translation layer. Measure startup time, navigation latency, memory pressure, PDF generation, and concurrency with your own pages; no general performance figure is established for this setup.
Emulation is often the least maintenance-intensive route for a small worker or a compatibility-first test environment. It is a poor assumption for high-throughput screenshot farms until you have measured it under realistic load.
Container permissions and writable storage
Keep the non-root user
The official image intentionally uses pptruser. If you copy application files or mount a cache, make sure that UID 10042 can read them and write the profile and cache directories. A root-owned mounted directory commonly produces browser startup or profile-lock errors.
Provide writable configuration paths
Chrome creates configuration and cache files while starting. Read-only container filesystems therefore need explicit temporary locations:
docker run -i --init --rm --cap-add=SYS_ADMIN
-e XDG_CONFIG_HOME=/tmp/.chromium
-e XDG_CACHE_HOME=/tmp/.chromium
-e PUPPETEER_USER_DATA_DIR=/tmp/.puppeteer-profile
ghcr.io/puppeteer/puppeteer:25.12.0
node app.jsIf your application sets userDataDir in code, use the writable path there instead of relying on an environment variable. Give each concurrent browser an isolated profile directory; sharing one profile between processes causes locks and corrupt state.
Prefer Debian over Alpine for the official path
Puppeteer’s troubleshooting guidance warns that Chrome does not support Alpine out of the box, and calls out Chromium/Puppeteer version matching and known Alpine timeout problems. Use the Debian-based official image unless you are prepared to own an Alpine-specific dependency set and its testing burden.
Troubleshoot the common failures
| Symptom | Likely cause | Fix |
|---|---|---|
exec format error |
The image or browser executable is for the wrong CPU architecture. | Use an ARM64 browser image/derivative or configure x64 emulation; verify image manifests and the browser binary architecture. |
“Failed to launch” with missing .so libraries |
Chrome for Testing dependencies were not installed in the derivative image. | Use the official Debian image, or install the complete dependency set from a compatible ARM64 Chromium package. |
| Browser starts, then exits as the container fills with zombies | No process reaping in PID 1. | Run with --init and ensure your orchestrator does not replace the init process. |
| Permission denied in cache or profile | A mounted directory is not writable by pptruser. |
Change ownership to UID 10042, mount a writable volume, or point cache/profile paths at /tmp. |
| Timeouts or hangs on Alpine | Unsupported or mismatched Alpine Chromium/Puppeteer combination. | Move to Debian, or pin and test a known-compatible Alpine pair. |
| Pages render differently after an upgrade | Chromium, Puppeteer, fonts, or system libraries changed. | Pin the image digest, compare browser versions, and promote upgrades only after visual and functional regression tests. |
| Sandbox errors when running as non-root | Kernel/container security settings do not permit the browser sandbox. | Keep the non-root user, review the container runtime policy, and use only the minimum capability your deployment can support; do not make the container root by default. |
Operational checklist for ARM deployments
- Confirm whether the host is Linux ARM64 or macOS ARM64; they have different Chrome support.
- Inspect the image manifest and browser executable architecture before rollout.
- Pin a reviewed image tag or digest and record Puppeteer/Chromium versions.
- Use a writable, isolated profile and cache for every worker.
- Run as
pptruser; check mounted-file ownership. - Use
--initand monitor browser-process cleanup. - Exercise the real workload, including PDFs, screenshots, lazy content, downloads, fonts, and authentication.
- For emulation, measure throughput and memory rather than assuming x64 performance.
- For third-party images, review publisher trust, update cadence, and supply-chain controls.
Or skip the browser setup
If your objective is reliable website screenshots rather than operating Chromium yourself, ScreenshotNeo provides a single HTTP endpoint and an MCP server for AI clients such as Claude and Cursor. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result.
One call returns a PNG, JPEG, WebP, or PDF:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for the 63 available options, including full-page and element capture, device presets, retina scale, PDF controls, custom CSS/JavaScript, clicks, waits, request blocking, headers and cookies, timezone and geolocation, transparent backgrounds, resizing, TTL caching, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage data, and the OpenAPI specification. Existing parameter names used by other screenshot APIs also work, easing migration.
Rank #3
- LATEST SOFTWARE SUPPORT: Fedora 42, Debian 13, Ubuntu 24.04 LTS, and CoreELEC support with hardware-accelerated video playback and 3D graphics. Upstream software stack featuring the latest Linux 6.x with open source graphics and video libraries.
- UEFI BIOS WITH ETHEREALOS: Full feature BIOS capable of web operating system deployment and automation built-in the ability to customize logo and messages. Supports booting from eMMC, MicroSD card, USB flash drive, and USB hard drives that are separately powered.
- EXTREME POWER EFFICIENCY: Designed for 24/7 operation with idle power usage of just 1W. LED light bulbs use 20 times the power of this board. Enough processing power to encrypt and max out network throughput for VPN operations.
- HARDWARE ACCELERATED 4K CODEC SUPPORT: Watch videos in Ultra HD 4K 10-bit goodness with CoreELEC OS designed for media playback. Capable of decoding H.264 H.265 and VP9 natively in 60 FPS.
- USB TYPE-C POWER: Standardize power input compatible with most power supplies with and without USB Power Delivery capability. Designed to draw up to 3A with 2A available for peripherals.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is on every plan. Create a free ScreenshotNeo account to try it.
FAQ
Does an Apple M1, M2, or M3 Mac have the same limitation?
No. The cited maintainer guidance distinguishes fully supported macOS arm64 from unsupported official Linux arm64 Chrome binaries. Your Docker Desktop Linux VM and chosen image still need to be checked independently.
Is the official tag a permanent version?
No. Registry tags and publication dates are volatile. Treat the shown 25.12.0 value as an example and pin a reviewed digest for reproducible releases.
Can I solve Linux ARM64 support by changing only Docker’s platform flag?
No. A platform flag selects the image architecture; it cannot manufacture a native ARM64 Chrome binary. You still need ARM64 Chromium, a derivative that supplies it, or x64 emulation.
Why does a successful launch test not prove production readiness?
Launch validates only startup. Rendering, fonts, PDFs, downloads, authentication, concurrency, and page-specific browser features can expose version, dependency, or architecture problems that a one-line smoke test misses.
Free tools Windows power users keep installed
One-click scans. No signup required.
Frequently Asked Questions
Can I run the official Puppeteer image natively on a Linux ARM64 Raspberry Pi?
Not with the image’s official Chrome for Testing binary. Use a compatible ARM64 Chromium image or derivative, or run the x64 image through emulation.
What is the safest way to update an ARM Puppeteer deployment?
Stage a new pinned image or digest, record its Puppeteer and Chromium versions, run your real screenshot/PDF regression suite, then promote it without changing architecture and browser versions implicitly.
Do I need Docker Buildx when my deployment machine is already ARM64?
Not necessarily. A native ARM64 builder can build directly, while Buildx is useful for producing an ARM64 image from an x64 workstation or for repeatable multi-platform pipelines.
Quick Recap
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.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →
