CircleCI has no separate field for a wkhtmltopdf version. Install the exact binary in a job step—or build it into a custom Docker image—then verify it with wkhtmltopdf --version. The dependable approach is to pin the executor image, package URL, architecture and (where available) checksum so a future package change cannot silently alter your PDFs.
Choose the installation strategy first
Your choice depends on whether the distribution package already meets the build requirement.
Use the executor’s apt package when it is sufficient
Ubuntu Jammy exposes wkhtmltopdf 0.12.6, while Debian Bookworm exposes 0.12.6-2 and Bullseye exposes 0.12.6-1. These packages are reasonable when you need the distribution version and its available feature set, rather than a particular upstream revision.
Use a versioned packaging release for an exact revision
The packaging project lists revisioned 0.12.6.1 assets, including wkhtmltox_0.12.6.1-3.bookworm_amd64.deb. Choose this route when your renderer depends on that revision or on a patched-Qt build, and only when the asset matches the job’s Linux distribution and CPU architecture. The packaging repository is archived, so record the URL and retain a local copy or checksum in your release process.
#1 Best Overall
- INNOVATIVE CARTRIDGE-FREE PRINTING — No more dealing with lots of tiny ink cartridges; With this wireless document and photo printer each ink bottle set is equivalent to about 90 individual cartridges²
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; When you choose this combination printer, scanner and copier you can print up to 4,500 pages black/7,500 color³
- COLOR PRINTING — Up to 2 years of ink in the box4 (and with every replacement ink set) for fewer out-of-ink frustrations
- ZERO CARTRIDGE WASTE — By using an Epson EcoTank printer you can help reduce the amount of cartridge waste ending up in landfills
- HOME PRINTER DESIGNED FOR RELIABILITY — The Epson EcoTank ET-2800 All-in-One Supertank Color Printer creates vivid, detailed prints and documents thanks to Micro Piezo Heat-Free Technology; Fire off 10 ISO pages per minute1 to easily finish large jobs
Build a custom image for frequent or large pipelines
Installing on every job is simple, but it repeats downloads. A custom image can contain the pinned binary and dependencies, reducing startup work and making the toolchain identical across jobs. Tag that image immutably; changing the tag behind CircleCI’s configuration defeats reproducibility.
What version should you expect?
The wkhtmltopdf project identifies 0.12.6, released June 11, 2020, as the current stable series. A 0.12.6.1 packaging revision is not the same thing as a new stable-series number: it is a revisioned package release. Ubuntu and Debian package indexes may therefore show 0.12.6 while the packaging repository offers 0.12.6.1-3 assets.
The original wkhtmltopdf repository is archived and directs users to the packaging repository for binaries. Treat every package URL as an explicit dependency, not as an invitation to download “latest.”
Install wkhtmltopdf 0.12.6.1 in a CircleCI job
This configuration uses a Debian Bookworm amd64 asset. It is a template, not a universal filename: change both the URL and filename for Jammy, Bullseye, ARM, or another executor.
- Open
.circleci/config.ymlin your repository. - Use a base image whose distribution and architecture match the package you selected.
- Install download prerequisites, fetch the pinned
.deb, install it, and verify the executable.
version: 2.1
jobs:
build:
docker:
- image: cimg/base:stable
steps:
- checkout
- run:
name: Install pinned wkhtmltopdf
command: |
set -euo pipefail
sudo apt-get update
sudo apt-get install -y ca-certificates curl
curl -L --fail --retry 3 -o wkhtmltox.deb
https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.bookworm_amd64.deb
sudo apt-get install -y ./wkhtmltox.deb
wkhtmltopdf --version
- run:
name: Render PDF
command: wkhtmltopdf input.html output.pdfThe final command should print the installed version before your actual rendering step runs. Keeping verification in the same job catches an executor or package mismatch immediately.
Adapt the package to your executor
Ubuntu Jammy
If Jammy’s 0.12.6 package meets your needs, use apt instead of a Bookworm file:
Rank #2
- CARTRIDGE-FREE PRINTING — Print lab-quality photos, graphics and creative projects; Get vibrant colors and sharp text with Epson's high-accuracy printhead and Claria ET Premium 6-color inks
- INK BOTTLES — Save on photos1 and creative projects with affordable in-house printing; All-in-one printer allows you to print 4" x 6" photos for about 4 cents each vs. 40 cents with traditional ink cartridges1
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; Printer, scanner and copier lets you print up to 6,200 color pages³
- PRINT FOR LONGER — Up to 2 years of ink in the box² (and with every replacement ink set) for fewer out-of-ink frustrations with this wireless printer
- ZERO CARTRIDGE WASTE — Epson EcoTank printer helps reduce the amount of cartridge waste ending up in landfills; Cartridge-free printer uses high-yield ink bottles; Each replacement ink bottle set is equivalent to about 100 individual ink cartridges⁴
sudo apt-get update
sudo apt-get install -y wkhtmltopdf
wkhtmltopdf --versionDo not install a Debian Bookworm package into Jammy merely because the filename contains a newer revision. Native dependencies and patched-Qt behavior can differ.
Debian Bullseye or Bookworm
For a distribution package, install the version exposed by that release. For 0.12.6.1, select the packaging asset whose distribution label exactly matches the executor. The example filename ends in bookworm_amd64.deb; it is not an ARM or Bullseye package.
Free tools Windows power users keep installed
One-click scans. No signup required.
ARM or another architecture
Inspect the packaging release assets and select an artifact for the job’s architecture. If no matching binary exists, use the distribution package or build an image that compiles wkhtmltopdf for that architecture. Never rely on a successful download alone: a package for the wrong architecture will fail during installation or execution.
Pinning for reproducible builds
- Pin the base image: replace a moving tag with the immutable image tag or digest approved by your team.
- Pin the package URL: use the complete revisioned release URL, not a redirect to an unversioned asset.
- Verify integrity: store and check a SHA-256 checksum when your release process provides one.
- Keep the package: archive the downloaded file or mirror it internally if your builds must survive an upstream repository change.
- Log the result: retain
wkhtmltopdf --versionoutput with the CircleCI job artifacts.
These controls separate a stable toolchain from a build that changes whenever a package index or image tag changes.
When apt is preferable to the official packaging release
| Need | Better fit | Reason |
|---|---|---|
| Distribution-supported 0.12.6 and ordinary rendering | apt package | It follows the executor’s dependency set and is maintained through that distribution’s package channel. |
| Specific 0.12.6.1 revision or patched-Qt behavior | Matching packaging release asset | The revision is explicit and can be pinned to a file and checksum. |
| Many jobs requiring identical setup | Custom Docker image | Installation happens once when the image is built rather than on every job. |
Evaluate exact revision, patched-Qt requirements, operating system, architecture, reproducibility and maintenance status together. A newer number is not automatically a better match for your executor.
Dependencies, fonts and rendering differences
Installing the binary does not guarantee identical output. PDF layout can change with fonts, locale, timezone, input HTML, network resources and Qt behavior. Put required fonts and rendering assets in the same image or install step, and make the locale and timezone explicit when output must be byte-for-byte comparable. If your pages load remote resources, ensure the CircleCI job can reach them and wait for the page’s required content before conversion.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsRank #3
- SET IT UP ONCE AND PRINT WITH CONFIDENCE. No complicated maintenance. Just easy, reliable printing you can count on.
- INK FOR YEARS. NOT MONTHS. Up to 2 years of ink included. Get thousands of pages of cartridge-free printing. More pages, less hassle
- KEEPS PRINTING WELL AFTER COMPETITORS HAVE QUIT. No complex maintenance. Sharper text, richer colors.[2] Only with HP Smart Tank
- PREMIUM SUPPORT - Strong technical expertise to solve issues faster
- THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.
Use a small fixture document in CI. It should exercise the CSS, images and page breaks that matter to your application; a version check alone cannot detect a visual regression.
Security: treat HTML as code
The wkhtmltopdf project warns: “Do not use wkhtmltopdf with any untrusted HTML – be sure to sanitize any user-supplied HTML/JS, otherwise it can lead to complete takeover of the server it is running on!” Apply that warning to CI as well as production. Sanitize user content, isolate rendering jobs, restrict network access where practical, and avoid passing attacker-controlled command-line options. A CircleCI job that renders arbitrary HTML should not have unnecessary credentials or write access to deployment systems.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common failures and fixes
“Unable to locate package”
The package is not in the configured repositories, or apt metadata is stale. Run sudo apt-get update, confirm the executor distribution, and use the distribution’s documented package name. If you require 0.12.6.1, download its matching release asset instead of expecting apt to provide that revision.
“404 Not Found” while downloading
The release URL or filename is wrong, or the asset was moved. Check the packaging release’s exact asset name and preserve its case, distribution label and architecture. Keep a mirrored copy for long-lived pipelines.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Package architecture or dependency errors
The asset does not match the executor. Compare dpkg --print-architecture and the distribution release with the package filename. Select a matching asset or switch to a compatible base image.
Command not found after installation
Installation may have failed, or the executable is not on PATH. Make the install command fail the step, then run command -v wkhtmltopdf and wkhtmltopdf --version. Do not continue to PDF generation after a failed install.
Rank #4
- Wireless Bluetooth Printer: Portable thermal printer compatible with iPhone, Android phones, iPad and tablet computers via Bluetooth. For smartphones, please download the "Nada Print" App. You can also connect to laptops and computers for printing using a USB-C cable. (Note: Laptops and computers can only be connected via USB and require the installation of a driver first. Bluetooth connection is not supported.)
- No-ink printing: Only supports US Letter and A4 size thermal paper.(Doesn't support regular paper) The no-ink portable thermal printer uses direct thermal technology, requiring no ink, toner or ribbons, making it environmentally friendly, cost-effective and time-saving. The thermal printer package comes with a roll of US Letter thermal printing paper. Note: When installing the paper, remember to switch the paper size switch on APP
- Clear Print: NDYIN N80 portable thermal printer adopts high-definition printing technology, with a 203DPI resolution to provide you with clear printing results. This mobile printer is compatible with roll paper, folded paper and tattoo transfer paper, supporting printing from your mobile phone PDF, Word, pictures and web pages anytime and anywhere. It is recommended to use our NDYIN thermal paper to achieve good printing quality
- Portable wireless printer for travel: The thermal printer is equipped with a built-in 1500mAh rechargeable battery, which can print 160 sheets of 8.5" x 11" thermal paper after being fully charged. It weighs only 1.5 pounds and is compact in size. This ink-free portable printer can be easily carried in a backpack or briefcase! It is perfect for business travel, cars, small offices, construction sites, schools and homes. You can print documents, contracts, invoices and boarding passes anytime and anywhere
- The N80 thermal printer has a wide range of uses. The package includes the N80 printer, a roll of US Letter paper(7m/roll), a user manual, a guide card, a type-C soft cable and a type C adapter. Note: The charging adapter is not included. Special thermal paper is required for use; ordinary paper cannot be used. This ink-free portable thermal printer is suitable for various scenarios such as home, school, travel, office, and outdoor, meeting the printing needs of different groups of people. This tattoo template printer is also compatible with tattoo transfer paper, making it an ideal choice for tattoo art
Blank or incomplete PDFs
The problem may be page content rather than the version. Check that required assets are reachable, fonts are installed, and the input HTML is sanitized and valid. Reproduce with the same fixture in the same image, then compare the distribution package with the pinned packaging build if patched-Qt behavior is relevant.
Works locally but not in CircleCI
Compare OS release, architecture, fonts, locale, timezone, environment variables and network access. Log the binary version and use a custom image when those inputs must remain fixed.
Performance and cost considerations
Downloading and installing a package adds startup time to each fresh job. Caching the package, using a custom image, or running multiple rendering commands in one job can reduce that overhead. A custom image shifts work to image maintenance, so rebuild it deliberately when the base image or security policy changes. CircleCI compute usage depends on your account and executor; the wkhtmltopdf package itself does not create a special CircleCI charge.
Or skip the browser setup
If your actual need is clean website screenshots rather than server-side HTML-to-PDF rendering, ScreenshotNeo provides a single HTTP request. It accepts cookie and consent banners like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and bills only clean shots: bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed. Responses identify the result with X-Page-Verdict and X-Billed headers.
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 all options. The service also offers an MCP server with take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients. Free accounts include 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Frequently Asked Questions
Does CircleCI support a wkhtmltopdf version field in config.yml?
No. Version selection belongs in the job’s installation step or in the Docker image used by the job.
Recommended Free Tools
Can the Bookworm amd64 package be used in every CircleCI Linux executor?
No. Its distribution and architecture must match the executor; choose another asset or package for Jammy, Bullseye or ARM.
Is wkhtmltopdf 0.12.6.1 a new stable series?
No. 0.12.6 is the stable series; 0.12.6.1-3 identifies a revisioned packaging release.
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.
