DEV Community: Vitalii Nemudryi

Chromium in Docker without --no-sandbox: what actually breaks

Vitalii Nemudryi — Fri, 18 Sep 2026 18:09:10 +0000

Disclosure up front: I'm Vitalii, founder of PDFik, a hosted URL/HTML-to-PDF API. The product shows up once near the end, clearly marked. The rest is what running sandboxed Chromium in production actually looks like — including the part where our own security audit got it wrong.

If you have ever put headless Chromium in a container, you have probably met one of these two messages:

Failed to move to new namespace: PID namespaces supported, Network namespace supported, but failed: errno = Operation not permitted

FATAL:zygote_host_impl_linux.cc - No usable sandbox! […]
If you want to live dangerously and need an immediate workaround, you can try using --no-sandbox.

And you have certainly seen the standard fix, repeated in countless Dockerfiles, quickstarts and accepted Stack Overflow answers: pass --no-sandbox. It makes the error go away immediately, so it spread everywhere — to the point where the flag reads like a required incantation for "Chrome in Docker" rather than what it actually is: switching off the browser's main defense against the content it renders.

Even our own security audit believed the myth

We run a PDF-rendering service: worker pods pull jobs from a queue and render customer-submitted URLs or HTML in headless Chromium via Playwright. The worker container is deliberately unfriendly — non-root, all Linux capabilities dropped, privilege escalation forbidden, read-only root filesystem.

During a security audit of that setup, the auditor looked at the pod spec and wrote the finding as fact: with a configuration this locked down, Chromium cannot even start without --no-sandbox.

Except the flag had already been removed in an earlier hardening round. The same locked-down pods had been rendering untrusted pages in production the whole time, sandbox on, end-to-end suite green.

I like this story because nobody in it is careless. The auditor pattern-matched the same folklore every tutorial repeats, and the folklore contains a real kernel of truth: in that container, one of Chromium's two sandboxes genuinely cannot work. The only mistake is not knowing there are two.

(The audit round still earned its keep: it is why the pod now pins a seccomp profile explicitly (RuntimeDefault) instead of running unconfined, which is what Kubernetes gives you by default when the field is absent. More on that below.)

The two sandboxes, in plain words

Chromium splits itself into a trusted browser process and untrusted renderer processes. The renderers execute whatever the page supplies — HTML parsing, JavaScript, images, fonts. Renderer bugs are found and patched all the time; the sandbox is the wall that decides what a successful exploit is worth. With the wall, code execution in a renderer lands in a process that has no filesystem, no network sockets of its own and no real user identity, and still needs a second, unrelated bug to get anywhere. Without the wall, it lands directly in your worker process: your environment variables, your tokens, your network position.

To build the wall, Chromium has two mechanisms.

The setuid sandbox is the legacy one: a small root-owned helper binary that briefly elevates to root to construct the isolation, then drops everything. In a hardened container this path is dead on arrival — and that is on purpose. allowPrivilegeEscalation: false sets the kernel's no_new_privs bit on the process, which means: nothing this process executes may ever gain privileges it does not already have. That bit exists precisely to neutralize setuid tricks. You did not want a root-elevating helper in your image anyway.

The user-namespace sandbox is the modern one, and it needs no privileges at all — when the environment permits it. An ordinary process asks the kernel for a new user namespace: a private view of the system in which the process is "root" while remaining a nobody outside. Chromium uses that namespace-root to strip its renderers of the filesystem, the network and everything else. Two switches decide whether this works:

The kernel must allow unprivileged user namespaces. Many distributions enable this by default; some disable or restrict it (Debian historically gated it behind a sysctl, recent Ubuntu restricts it through AppArmor). Inside the container, cat /proc/sys/user/max_user_namespaces returning 0 means the kernel says no.
The seccomp profile must allow the namespace syscalls. Seccomp is the allowlist of kernel calls a container may make. Docker's historic default profile blocked creating user namespaces — that block is exactly where Failed to move to new namespace … Operation not permitted comes from, and where the --no-sandbox cargo cult started.

Both switches vary by distribution, container runtime and version, and both have flipped over the years. So do not memorize a compatibility table — probe. Remove the flag, launch once, read the error: the message tells you which mechanism failed and why.

The pod spec that runs Chromium with its sandbox ON

This is the real production configuration of our render workers on Kubernetes (EKS; the node kernel ships with unprivileged user namespaces enabled — the default on Amazon Linux 2023):

spec:
  securityContext:          # pod-level
    runAsNonRoot: true
    runAsUser: 1000
    fsGroup: 1000
    seccompProfile:
      type: RuntimeDefault
  containers:
    - name: render-worker
      securityContext:      # container-level
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        capabilities:
          drop: ["ALL"]

With a read-only root filesystem, Chromium still needs somewhere to write, so three emptyDir volumes are mounted: /tmp, the app's own scratch directory, and the browser user's home. The image creates a real non-root user (uid 1000) with a home directory — Chromium wants one for its profile. And here is the complete list of Chromium flags we pass — all two of them:

browser = await playwright.chromium.launch(
    headless=True,
    args=["--disable-dev-shm-usage", "--disable-gpu"],
)

No --no-sandbox, no --disable-setuid-sandbox, no added capabilities, no custom seccomp JSON. --disable-dev-shm-usage is there because a container's /dev/shm is 64 MB by default and Chromium crashes on heavy pages when shared memory runs out; the flag makes it use ordinary temp files instead. (The alternative is mounting a memory-backed volume on /dev/shm.) --disable-gpu because there is no GPU to find.

One operational consequence to plan for: the namespace sandbox depends on the node's kernel settings, which you usually do not manage directly. A node-image upgrade that disables unprivileged user namespaces will not degrade your service politely — Chromium will simply refuse to launch. That is the right failure direction (closed), but it is still an outage, so make it loud and early. Our workers refuse to come up without the browser pool: if Chromium cannot launch, the process exits during startup and the replacement pods crash-loop, so a missing sandbox prerequisite reads as "the rollout never goes healthy" at deploy time, not as customer-facing errors an hour later. (A separate liveness probe catches the other failure mode: a browser pool or event loop that wedges after startup.)

What the sandbox does nothing about

Here is the part most "secure headless Chrome" writeups skip: a perfectly sandboxed browser still makes network requests on behalf of untrusted content, because fetching things is what a browser is for. If you render customer-submitted URLs from inside your infrastructure, the bigger everyday risk is not a renderer exploit — it is the page politely asking for things it should never reach: http://169.254.169.254/… (the cloud metadata service that hands out credentials), your database, internal dashboards. The sandbox is completely indifferent to all of that.

So the second half of rendering untrusted content responsibly is controlling what the browser can reach — and the obvious first tool, application-level URL filtering, has traps we have personally hit.

1. Validate-then-fetch is a race. You resolve invoice.example.com, get a public IP, approve the URL — and the browser resolves the name again at connect time, when the attacker's DNS can answer with a private address. This is DNS rebinding. The counter is to resolve once, validate every address the name resolves to, and pin the connection to a validated IP wherever your HTTP client allows it. Inside Chromium you effectively cannot pin — the browser re-resolves on its own. Hold that thought; it is why the network-policy section below exists.

2. The standard library's idea of "private" has a hole in it. Python shown, but the same trap exists in other stacks:

>>> import ipaddress
>>> ipaddress.ip_address("10.0.0.1").is_private
True
>>> ipaddress.ip_address("100.64.0.1").is_private
False

100.64.0.0/10 is RFC 6598 shared address space (carrier-grade NAT), deliberately classified as neither private nor global — and inside cloud networks that range can be very much alive. A blocklist built on is_private alone waves it through. Block it explicitly, along with loopback, link-local, multicast, reserved and unspecified.

3. IPv6 can smuggle IPv4.

>>> ipaddress.ip_address("64:ff9b::169.254.169.254").is_private
False

64:ff9b::/96 is the well-known NAT64 prefix: the last four bytes are an embedded IPv4 address, and a NAT64-capable egress path will deliver the packet to that inner address — here, the metadata service. To the standard library the outer address is ordinary global IPv6 space. The same wrapper trick exists in IPv4-mapped (::ffff:a.b.c.d) and IPv4-translated forms; newer language versions unwrap some of them in some checks. Do not memorize which: if an IPv6 address embeds an IPv4 address, extract the inner address and judge that.

4. The first URL is not the last URL. Validating what the customer submitted misses everything that happens next: redirects (302 → http://169.254.169.254/…) and every subresource the page pulls in — images, iframes, stylesheets, fonts. Subresources you can catch by hooking the browser's network layer: in Playwright, a route handler sees every request the page makes and can re-validate each one. Redirect hops you cannot: Playwright's documented behavior is that the handler "will only be called for the first url if the response is a redirect" — and that holds for context.route too — so the browser follows a 302 without your handler ever seeing the new URL. To police redirects at this layer you have to take over the fetch inside the handler (route.fetch(max_redirects=0), validate each Location target yourself, then route.fulfill()), or refuse redirects on render targets outright. Otherwise a redirect to the metadata service passes the hook untouched — one more reason the next section exists. In Playwright:

async def interceptor(route, request):
    try:
        # Resolve-once + blocklist check on every request the page makes.
        # NOTE: Playwright does NOT call this handler for redirect hops —
        # only for the first URL of a chain. Police redirects with
        # route.fetch(max_redirects=0) here, or leave them to the
        # egress policy below.
        await validate_url_for_ssrf(request.url)
    except SSRFError:
        await route.abort("accessdenied")
        return
    await route.continue_()

await context.route("**/*", interceptor)

(If your jobs can carry customer credentials for authenticated rendering, this hook is also the place to attach them — per request, only when the request's origin matches the target's origin. Never install a credential context-wide: every third-party subresource on the page would receive it. And the redirect caveat applies here too: your handler does not see redirect hops, so verify with a live test what your browser and interception layer actually do with an injected header across a cross-origin redirect, rather than assuming the hook will strip it.)

The layer we actually trust

Everything in the previous section runs inside the same workload that renders hostile content, and one of its counters — IP pinning — is not even fully available in a browser. So the honest architecture statement is: application-level SSRF filtering is best-effort, and the control we actually rely on sits one level down — a kernel-enforced egress policy on the render pods. In Kubernetes terms:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: render-workers-egress
spec:
  podSelector:
    matchLabels:
      app: render-workers
  policyTypes: ["Egress"]
  egress:
    # DNS
    - to:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: kube-system
      ports:
        - { protocol: UDP, port: 53 }
        - { protocol: TCP, port: 53 }
    # The database — and no other private destination
    - to:
        - ipBlock: { cidr: <your-db-subnet> }
      ports:
        - { protocol: TCP, port: 5432 }
    # Public HTTP/HTTPS: render targets, object storage, queues
    - ports:
        - { protocol: TCP, port: 80 }
        - { protocol: TCP, port: 443 }
      to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except:
              - 10.0.0.0/8
              - 100.64.0.0/10
              - 172.16.0.0/12
              - 192.168.0.0/16
              - 169.254.0.0/16

With this policy enforced, a page that gets past every software check above finds its packets to the metadata service or the internal network dropped by infrastructure the rendered content has no influence over.

Two scars to save you time here.

A NetworkPolicy is a request, not a fact. Kubernetes happily accepts NetworkPolicy objects on clusters where nothing enforces them — on EKS with the AWS VPC CNI, enforcement is a flag you must explicitly turn on. Ours sat in exactly that state for a while: accepted, visible in kubectl, doing nothing.

An unenforced policy accumulates bugs invisibly. When enforcement was finally switched on, probing from a live worker pod found three defects that had been sitting in that green-looking YAML the whole time: the blanket private-range block also covered the range our own database lives in, so workers could not record job results; only port 443 had been allowed, so any plain-http:// render target would hang; and there was an allow rule for a Redis connection the workers never actually make. The policy had reviewed well and meant nothing. So: after enabling enforcement, prove both directions from inside a pod — the metadata request must fail, the database connection must succeed, an http:// fetch must succeed — and grant only what you can demonstrate the workload uses.

The checklist

If you render untrusted URLs or HTML with headless Chromium, in rough order of value:

Run the sandbox. Do not pass --no-sandbox; when launch fails, fix the switch the error names instead — kernel user-namespace sysctl, seccomp profile, non-root user with a writable home. If your runtime's default seccomp profile blocks the namespace syscalls, prefer a tailored profile over running unconfined.
Harden the container anyway: runAsNonRoot, allowPrivilegeEscalation: false, capabilities: drop ALL, readOnlyRootFilesystem with emptyDir for /tmp and the home directory, an explicit seccomp profile.
Prove at startup that the browser actually launches, and fail the rollout loudly — a node-image change can silently remove a sandbox prerequisite.
One browser context per job, downloads off, popups closed, context torn down in finally.
Validate URLs with resolve-once semantics; block CGNAT explicitly; unwrap IPv4-embedding IPv6 forms; re-validate every request in a network hook — subresources included — and know your tool's redirect behavior: Playwright's route handler does not see redirect hops, so police redirects separately or leave them to the egress layer below.
Put the real guarantee below the application: a kernel-enforced egress policy that denies private ranges, CGNAT and link-local, allows only DNS, your database and public 80/443 — then prove it empirically from inside a pod.
Assume each layer fails. The useful design question is never "is this isolated?" — it is "what does the next layer catch?"

The plug, as promised

PDFik is roughly this article as a service: a hosted URL/HTML-to-PDF API where the posture above is the default — Chromium with its sandbox on, a fresh browser context per job, per-request SSRF re-validation, and network-level egress restrictions on the render fleet — all running on AWS in the EU (Frankfurt). There is a free plan and it does not ask for a credit card: pdfik.net.

If you spot a hole in any of this, I genuinely want to know — that is half the reason to write it up.

Factur-X / ZUGFeRD from HTML: how to embed EN 16931 XML in a PDF/A-3 and actually pass veraPDF and Mustang

Vitalii Nemudryi — Tue, 08 Sep 2026 14:22:49 +0000

Disclosure up front: I'm Vitalii, founder of PDFik, a hosted URL/HTML-to-PDF API. We shipped Factur-X output this week, and this article is the write-up of what it took. PDFik appears once near the end, clearly marked, next to the self-hosted paths that compete with it. If you must keep invoices on your own infrastructure, the self-hosted section is for you and the hosted one is not.

If you already render invoices from HTML, turning them into hybrid e-invoices looks like a small step: attach an XML file to the PDF. It is not a small step. The container has to be PDF/A-3, the attachment has to carry the right relationship, the metadata has to declare a custom schema, and two of the most common mistakes pass both validators everyone uses.

Here is what a valid file actually contains, the pipeline we ended up with, the traps that cost us days, and three ways to build it yourself.

Why a hybrid PDF at all

Factur-X (France) and ZUGFeRD 2.x (Germany) are the same standard under two names: one PDF that a human reads, with a UN/CEFACT Cross Industry Invoice (CII) XML embedded for the accounting system. The XML follows the European semantic model EN 16931.

Where this matters:

Germany. Domestic businesses have had to be able to receive e-invoices since 1 January 2025 — small businesses included, even though they are exempt from issuing them. Issuing is phased in through a transition rule: until 31 December 2026 any issuer may still send an "ordinary invoice" instead, and until 31 December 2027 if their previous year's turnover was €800,000 or less. Note what an ordinary invoice means there: paper, or an unstructured electronic file such as a plain PDF — and the electronic variant, exactly as before, may only be used if the recipient agrees to that format. So in practice the duty to issue bites from 2027 for larger companies and from 2028 for the rest. The BMF names XRechnung and ZUGFeRD from version 2.0.1 as satisfying the VAT-law requirements, with the MINIMUM and BASIC-WL profiles explicitly excluded (BMF FAQ).
France. Since 1 September 2026 every business covered by the reform must be able to receive electronic invoices, and reception runs through an approved platform. Large enterprises and mid-caps (ETI) must also issue from that same date; SMEs, small firms and micro-enterprises must issue from 1 September 2027 (DGFiP start-up guide, PDF). Approved platforms are required to transmit invoices in one of three formats — CII, UBL, or Factur-X, described there as a mixed format of structured XML plus a readable PDF (DGFiP fiche, PDF).
Belgium went the other way: B2B e-invoicing has been mandatory since 1 January 2026 over Peppol, and "sending a PDF invoice by e-mail or via a platform will no longer be enough" (source). The hybrid PDF is a courtesy copy there, not the legal document.
Poland's KSeF takes structured XML only. The FA(3) logical structure replaced FA(2) on 1 February 2026 (structure page), and issuing through KSeF has been mandatory since 1 February 2026 for the largest taxpayers and since 1 April 2026 for the rest — with temporary carve-outs running to the end of 2026, notably for issuers whose invoiced sales stay at or below 10,000 zł in a month (legal basis and key dates). Even an invoice "attachment" there is a structured element inside the FA(3) XML, and using it at all requires notifying the tax office first (FA(3) brochure, PDF) — so a hybrid PDF has nothing to attach itself to.

So the hybrid PDF is the right target for Germany and France, and a human-readable extra everywhere else. Nothing below generates the XML for you. That is your accounting data, and every path here assumes you already have valid CII.

What a valid Factur-X file actually requires

Four layers, and every one of them can be wrong independently.

1. The container is PDF/A-3. Chromium gives you a plain PDF. PDF/A-3b on top of it needs an OutputIntent with an embedded sRGB ICC profile, XMP metadata carrying pdfaid:part=3 and pdfaid:conformance=B, every font embedded, no JavaScript and no encryption. PDF/A-3b permits transparency, so CSS opacity is not the problem it was under PDF/A-1.

Chromium embeds what it renders. Across a dozen local test renders — Latin, Cyrillic, Greek, CJK, SVG text, form controls, a web font fetched from Google Fonts, a family that does not exist anywhere — every text font landed in the file as a subsetted CIDFontType2 with its outlines in /FontFile2: one line of text pulled a 1 MB, 4,651-glyph face down to a 47 KB subset, and a character no installed font covers is drawn as the empty box out of a font that is already embedded. Two caveats, both of which cost us work. A font whose OS/2 fsType forbids embedding is not embedded: Chromium converts it to a Type3 font and writes the glyph outlines into the PDF itself, which is a different construct from everything else in the file — worth putting through your own validator before you ship an invoice template built on a licensed corporate typeface. And Chromium neither installs fonts nor touches anything you draw outside it: our worker image adds DejaVu, Lato, Open Sans, Roboto and Noto core on top of the Playwright base, and the sandbox watermark registers and embeds its own TTF, failing the job outright when it cannot find one.

2. The embedded file has the right name. For Factur-X the attachment is factur-x.xml for every profile, listed under /Names/EmbeddedFiles and referenced from the catalog's /AF array.

3. The AFRelationship value. The file specification carries /AFRelationship, and Factur-X gives it meaning in section 6.2.2: Data when the visual representation carries more invoice data than the XML, Source when the visual representation was produced from the XML, Alternative when the two carry exactly the same invoice content in two forms. MINIMUM and BASIC WL never carry a complete invoice, so both countries require Data there. For BASIC, EN 16931 and EXTENDED the two countries part ways: in France Data, Source or Alternative are all allowed, "depending on how the PDF part was created", while for use in Germany the specification makes Alternative mandatory — the word is "zwingend", on legal grounds, because the value asserts that the tax-relevant content of both representations is identical. That is sections 5.3 and 6.2.2 of Factur-X 1.07.2 / ZUGFeRD 2.3.2, 15 November 2024; the spec is free but email-gated at fnfe-mpe.org, and a third-party mirror of that edition is readable without the form. The current release is 1.09.2 / ZUGFeRD 2.5.2, whose published changes are code lists, validation artifacts and new EXTENDED elements — I have not read it, so treat the version above as the one these quotes come from. One thing worth being clear about: Source is not our case. We render the PDF from your HTML and embed your XML, so the two are independent inputs and neither we nor a validator can tell whether they agree. Alternative is a claim about your data, and it is yours to make true.

Here is the trap. The Python factur-x library defaults to data, and quietly downgrades alternative to data only for the two small profiles. Call it with defaults for an EN 16931 invoice and you get a structurally perfect file with the wrong relationship, and nothing downstream objects. Mustang's validator never looks at the value at all — the word "relationship" does not appear in any of the nine source files of its validator module — and veraPDF checks the container, not whether the PDF and the XML "say the same thing", which is not something a validator can decide from the bytes anyway. You have to pass the value explicitly and assert it in your own tests.

4. The XMP extension schema. PDF/A only allows custom XMP properties that are declared in a pdfaExtension:schemas block. Factur-X defines the namespace urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0# with four properties: fx:DocumentType (INVOICE), fx:DocumentFileName (factur-x.xml), fx:Version (1.0) and fx:ConformanceLevel. The last one is spelled per profile, and the spelling is not your API's key:

API profile	`fx:ConformanceLevel`	`AFRelationship` (German rule)	Complete legal invoice?
`minimum`	`MINIMUM`	`Data`	no
`basicwl`	`BASIC WL`	`Data`	no
`basic`	`BASIC`	`Alternative`	yes
`en16931`	`EN 16931`	`Alternative`	yes
`extended`	`EXTENDED`	`Alternative`	yes

Note the spaces in BASIC WL and EN 16931. A misspelled level is catchable: Mustang's PDFValidator matches the XMP value against a fixed list — as of Mustang 2.26 that is BASIC WL, BASIC, MINIMUM, EN 16931, COMFORT, CIUS, EXTENDED, XRECHNUNG, a superset of the five Factur-X levels above — exactly and case-sensitively, and anything outside it is reported as <error type="12">XMP Metadata: ConformanceLevel contains invalid value</error>. A level that is missing entirely raises type="11" ("ConformanceLevel not found") and, because the membership check then fails too, type="12" alongside it — validator source. What it does not catch is a level that is on the list but disagrees with the profile in the XML: the XML's own profile is read separately, and nothing in the validator compares the two, so BASIC in the XMP on an EN 16931 invoice draws no complaint. Keep the mapping in exactly one place in your code.

The pipeline

Four steps, and the order is load-bearing.

Render the HTML with Chromium (Playwright page.pdf()).
Normalise to PDF/A-3b with pikepdf: add the OutputIntent, set the pdfaid XMP properties. Anything you stamp onto the page (we stamp a demo watermark on anonymous sandbox output) has to happen before this step, or its font is not part of the file the PDF/A check sees.
Embed the XML with factur-x, passing afrelationship explicitly. The library copies the OutputIntent from its input and does not make a PDF/A itself, so step 2 must come first.
Validate with two tools: veraPDF with the 3b profile for the container, Mustang for the Factur-X structure and the XML.

The Mustang gotcha: do not gate on its exit code. In the validator source, the flag that decides overall validity is set from the XML result alone (wasCompletelyValid = xmlValidity); the PDF/A half is written into the XML report but does not change the verdict. A file with a broken PDF/A container and a valid XML exits 0 — and the report's last <summary status="..."> element is that same XML-only verdict, so reading it misses the same failures. The PDF half writes its own <summary> inside the <pdf> section, and that is where a broken container or a bad fx:ConformanceLevel shows up. Parse the report and require every <summary status="..."> element to say valid.

We rejected two alternatives on purpose. Ghostscript's pdfwrite can produce PDF/A, but it is AGPL, which for a closed-source service means a commercial licence, and we did not want to debug its output against veraPDF as well. If you are open source or already licensed, it is a legitimate path. And we do not run Schematron (the business rules of EN 16931) at request time: that needs a Java toolchain in the hot path. We validate against the profile XSD per request and run Mustang in the release gate. Schema-valid is not tax-compliant; the content stays the sender's responsibility either way.

The traps we hit

XML in a queue message. Our workers pull jobs from SQS, which caps a message at 256 KB. A 200 KB invoice XML grows past that once it is encrypted and base64-encoded, and the failure would land after the job row and the quota charge. The fix is gzip before encrypt, then a size check of the final serialised message before anything is charged. How much you save depends almost entirely on how repetitive the invoice is: the small single-page profile samples we measured gzip only 3–6x, while an invoice with hundreds of line items does far better. So do not size the check from a ratio at all — measure the final serialised message, and note that the envelope base64-encodes twice, once around the gzip bytes and once around the AES ciphertext, inflating them by about 1.8x before they ever reach the queue. On the consumer side, cap the inflated size again (we stop at 1 MB) so a corrupted message cannot become a zip bomb on your own data.

CSS watermarks do not survive customer CSS. For the anonymous sandbox we mark the output. A body::after watermark is removed by one !important in the customer's stylesheet, because in the "bring your own HTML" mode the page is theirs. The stamp is a PDF-level overlay drawn with an embedded TrueType font, applied before PDF/A normalisation. Paid or free accounts get no stamp at all; this is only about anonymous output.

libxml2's schema registry is process-global. On a freshly started worker, the first batch of jobs compiled the same XSDs in five threads at once, under Chromium memory pressure. libxml2's built-in type registry ended up corrupted for the life of the process, and every later job failed with xmlSchemaPValAttrNodeValue, the given type is not a built-in type. It does not reproduce in isolation. facturx.xml_check_xsd rebuilds the schema on every call, so we stopped using it at request time: compile each profile's schema once under a process-wide lock, warm all five up at startup so a broken environment fails the start instead of the customers' jobs, serialise validation through the same lock (it takes milliseconds; the compile is what costs), and exit the process when that error signature appears so the orchestrator restarts it.

Profile mismatch. The XML declares its own profile in GuidelineSpecifiedDocumentContextParameter/ID (urn:cen.eu:en16931:2017 for EN 16931). If the caller says en16931 and the XML says basic, do not pick one: reject. A silent upgrade produces a file whose XMP claims a level the XML does not meet.

pypdf pins. factur-x needs pypdf 5.3 or newer. Our worker was pinned to 4.2, and the unit tests stub pypdf, so the pin change was green in CI and only a real file proved it. If your tests mock the PDF library, one live render belongs in the gate.

The self-hosted route

Three stacks, one shape: get a PDF/A-3, then embed. All three snippets below were run as written on 2026-09-08 — the Python script end to end, the Java fragment compiled and executed against Mustang 2.26.0, the PHP one against horstoeko/zugferd v1.0.132 — and each output passed veraPDF (PDF/A-3b) and Mustang validation. They are still snippets, not products: error handling and your invoice data are on you.

Python: Playwright + pikepdf + factur-x

One installation gotcha: on PyPI the package is factur-x with a hyphen — pip install facturx finds nothing.

pip install factur-x pikepdf playwright && playwright install chromium

import io
import pikepdf
from pikepdf import Name, Pdf
from playwright.sync_api import sync_playwright
from facturx import generate_from_binary

AFRELATIONSHIP = {"minimum": "data", "basicwl": "data",
                  "basic": "alternative", "en16931": "alternative",
                  "extended": "alternative"}

def render(html: str) -> bytes:
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()
        page.set_content(html, wait_until="networkidle")
        pdf = page.pdf(format="A4", print_background=True)
        browser.close()
        return pdf

def to_pdfa3b(pdf_bytes: bytes, icc_path: str, title: str) -> bytes:
    pdf = Pdf.open(io.BytesIO(pdf_bytes))
    with open(icc_path, "rb") as fh:
        icc = pikepdf.Stream(pdf, fh.read())
    icc.N = 3
    intent = pikepdf.Dictionary(
        Type=Name.OutputIntent, S=Name("/GTS_PDFA1"),
        OutputConditionIdentifier=pikepdf.String("sRGB"),
        Info=pikepdf.String("sRGB IEC61966-2.1"),
        DestOutputProfile=pdf.make_indirect(icc),
    )
    pdf.Root.OutputIntents = pikepdf.Array([pdf.make_indirect(intent)])
    with pdf.open_metadata(set_pikepdf_as_editor=False) as meta:
        meta["pdfaid:part"] = "3"
        meta["pdfaid:conformance"] = "B"
        meta["dc:title"] = title
    out = io.BytesIO()
    pdf.save(out)
    return out.getvalue()

profile = "en16931"
xml_bytes = open("invoice.xml", "rb").read()
pdfa = to_pdfa3b(render(open("invoice.html").read()), "sRGB.icc", "Invoice INV-2026-0042")
final = generate_from_binary(pdfa, xml_bytes, flavor="factur-x", level=profile,
                             afrelationship=AFRELATIONSHIP[profile])
open("invoice-facturx.pdf", "wb").write(final)

Ship an sRGB ICC file in your image; pikepdf does not bundle one. Pin factur-x deliberately: the XSD set it bundles defines what you accept.

Java: Mustang (run and validated 2026-09-08; artifact org.mustangproject:library — 2.26.0 was the current release when this was written on 2026-09-07; check Maven Central for a newer 2.x)

<dependency>
    <groupId>org.mustangproject</groupId>
    <artifactId>library</artifactId>
    <version>2.26.0</version>
</dependency>

import org.mustangproject.ZUGFeRD.ZUGFeRDExporterFromA3;
import java.nio.file.Files;
import java.nio.file.Path;

byte[] xml = Files.readAllBytes(Path.of("invoice.xml"));

ZUGFeRDExporterFromA3 exporter = new ZUGFeRDExporterFromA3()
    .setProducer("my-billing")
    .setCreator("my-billing")
    .setProfile("EN16931")          // no space here; Mustang writes "EN 16931" into the XMP itself
    .load("invoice-pdfa3.pdf");
exporter.setXML(xml);               // must come after setProfile: this call attaches the file
exporter.export("invoice-facturx.pdf");

Mustang writes the factur-x.xml attachment and the fx: XMP block for you, and its AFRelationship default is the opposite of the Python library's. In ZUGFeRDExporterFromA3 the relationship starts as Alternative and is lowered to Data only when the profile is MINIMUM or BASICWL — and only if you called setProfile first, because the check reads that field. Skip the call and a MINIMUM invoice ships as Alternative. Two more things the source says and the docs do not: ignorePDFAErrors() compiles on this class but changes nothing, because ensurePDFIsValid here returns true unconditionally and load() never inspects the input — it is the ...FromA1 exporter that validates and throws. And its default conformance level is UNICODE (conformanceLevel = PDFAConformanceLevel.UNICODE, with overwrite = true), so the output declares pdfaid:conformance=U — PDF/A-3U, not 3b. setConformanceLevel(PDFAConformanceLevel.BASIC) makes it declare B instead; whichever letter you ship, validate against the level you claim.

PHP: horstoeko/zugferd (run and validated 2026-09-08 against tag v1.0.132; composer require horstoeko/zugferd)

<?php
require 'vendor/autoload.php';

use horstoeko\zugferd\ZugferdDocumentPdfMerger;

$merger = new ZugferdDocumentPdfMerger('/path/invoice.xml', '/path/invoice.pdf');
$merger->setAttachmentRelationshipTypeToAlternative();  // default is 'Data' — the same trap again
$merger->generateDocument();
$merger->saveDocument('/path/invoice-facturx.pdf');

This library repeats the Python default: ZugferdDocumentPdfBuilderAbstract initialises the attachment relationship to Data, so an EN 16931 invoice carries Data unless you say otherwise. It reads the profile out of your XML rather than taking it as an argument, names the attachment from the resolved profile (factur-x.xml for the Factur-X profiles, xrechnung.xml for XRechnung), writes the fx: block with the spaced EN 16931, and emits its own sRGB OutputIntent — the pages of your input are re-imported into a fresh document (FPDI) and the PDF/A metadata is written from scratch, so the input is a plain PDF here, not a PDF/A-3. Whether the result passes veraPDF still depends on what is inside those pages, fonts first. Whatever your stack, run the checklist at the end on the output; the libraries agree on structure and disagree on defaults.

The hosted route (this is mine)

PDFik's version of the same pipeline is POST /einvoice-to-pdf: you send the CII XML, we build the visual invoice from a block template (or you keep your own HTML, see below), normalise to PDF/A-3, embed with the profile-correct relationship and metadata, and hand back a job id. The output is validated with veraPDF and Mustang in our release gate, on every plan including Free, with no watermark on account output. The Free plan takes no credit card to start.

# invoice.xml is your UN/CEFACT CII file (EN 16931 profile)
jq -n --rawfile xml invoice.xml '{xml: $xml, profile: "en16931"}' > request.json

curl -X POST https://api.pdfik.net/einvoice-to-pdf \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

The response is 202 with {"job_id": "...", "status": "queued", ...}; poll GET /jobs/{job_id} and download from GET /jobs/{job_id}/download, or give a webhook_url. profile defaults to en16931. The XML is validated against the profile's XSD, its guideline URN must match the declared profile, and a rejected request costs nothing. Up to 1 MB of XML.

To keep your own design, add an einvoice block to POST /html-to-pdf or POST /url-to-pdf:

{
  "html": "<html>...your invoice...</html>",
  "einvoice": { "format": "factur-x", "profile": "en16931", "xml": "<rsm:CrossIndustryInvoice ..." }
}

It cannot be combined with user_password (PDF/A forbids encryption) or compression (re-saving breaks the PDF/A attributes); both are rejected with 422. The full reference is at docs.pdfik.net/einvoicing, and the homepage sandbox runs the same pipeline on pasted XML without an account, watermarked, a few renders per day.

When the hosted route is the wrong choice: if you are air-gapped or your policy requires documents to never leave your own infrastructure, self-host. Same answer if you already operate Mustang in a Java stack, or if your volume makes per-document pricing lose to your own servers. It also accepts CII only; UBL input is not supported today. (Since September 2026 PDFik runs on AWS in the EU — Frankfurt, Germany — so invoice data is processed and stored in the EU.)

A validation checklist you can run

Run all four on every build, not once.

# 1. PDF/A-3b container — assert the value; a missing line must FAIL, not print nothing
verapdf -f 3b --format xml invoice-facturx.pdf \
  | grep -q 'isCompliant="true"' && echo "PDF/A OK" || { echo "PDF/A FAIL"; exit 1; }

# 2. Factur-X structure + XML; never the exit code — and never only the LAST
#    summary: both come from the XML half alone (wasCompletelyValid = xmlValidity),
#    so a broken PDF/A half or a bad ConformanceLevel only turns the <pdf>
#    section's own <summary> invalid while the last one stays "valid". Require
#    EVERY summary to be valid, and assert at least one exists (Mustang
#    crashed or the report format changed = no match = FAIL)
report=$(java -jar Mustang-CLI.jar --no-notice --action validate --source invoice-facturx.pdf)
echo "$report" | grep -q '<summary status=' \
  && ! echo "$report" | grep -o '<summary status="[a-z]*"' | grep -qv 'status="valid"' \
  && echo "Factur-X OK" || { echo "Factur-X FAIL"; exit 1; }

# 3 + 4 + 5. The things the validators do not check for you
import re, pikepdf

pdf = pikepdf.open("invoice-facturx.pdf")
print([str(fs.get("/AFRelationship")) for fs in pdf.Root.AF])   # ['/Alternative'] for en16931
names = pdf.Root.Names.EmbeddedFiles.Names
print([str(names[i]) for i in range(0, len(names), 2)])           # ['factur-x.xml']
with pdf.open_metadata() as meta:
    xmp = str(meta)
print(re.findall(r"fx:ConformanceLevel[^<]*", xmp))              # 'EN 16931', with the space
print("pdfaid:part" in xmp, pdf.Root.get("/OutputIntents") is not None)

# 5. The binding no validator performs: the XMP level must agree with the XML's
#    own guideline URN. Mustang reads both but never compares them.
URN_TO_LEVEL = {
    "urn:factur-x.eu:1p0:minimum": "MINIMUM",
    "urn:factur-x.eu:1p0:basicwl": "BASIC WL",
    "urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:basic": "BASIC",
    "urn:cen.eu:en16931:2017": "EN 16931",
    "urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended": "EXTENDED",
}
xml = pdf.attachments["factur-x.xml"].get_file().read_bytes().decode("utf-8")
urn = re.search(r"Guideline\w*DocumentContextParameter>\s*<[^>]*ID[^>]*>([^<]+)", xml).group(1).strip()
level = re.search(r'fx:ConformanceLevel(?:>|=")([^<"]+)', xmp).group(1)
assert URN_TO_LEVEL[urn] == level, (urn, level)

Then the boring ones: TypeCode is 380 or 381; the PDF shows every amount the XML carries (otherwise Alternative is a lie); the file opens in Adobe Reader with the attachment visible; and a wrong profile, a DTD in the XML, and an unembedded font each fail your pipeline loudly instead of producing a file.

One more trap, raised in the comments: the business-rule layer has the same versioning problem as the container layer. XRechnung Schematron packs from KoSIT are date-gated — in a transition window two versions are in force at once, so an invoice can pass the current pack while failing the one that actually applied on its issue date, and nothing in the PDF layer catches that. This checklist deliberately stops at the container and the structural XML; Schematron business rules stay with the receiving side. If you do validate them yourself, pin every Schematron pack and codelist by version.

Library defaults, validator behaviour and mandate dates last verified: 2026-09-07 — factur-x 6.8, Mustang 2.26.0 (library and validator sources), horstoeko/zugferd v1.0.132, and the BMF, DGFiP and KSeF pages linked above. Checklist tightened 2026-09-18 after reader feedback and a full re-verification of every block in this article (each one executed, plus the failure directions): the shell checks now assert their values, the Mustang gate requires every <summary> in the report to be valid (the last one alone is the XML-only verdict and misses PDF-half failures — proven live on Mustang 2.26.0), and the XMP-level-vs-guideline-URN binding moved from prose into code. If something here is outdated, tell me and I'll fix it.

wkhtmltopdf in Docker in 2026: musl, libssl1.1, and the ways out

Vitalii Nemudryi — Thu, 27 Aug 2026 09:24:16 +0000

Disclosure up front: I'm Vitalii, founder of PDFik, a hosted URL/HTML-to-PDF API. It shows up once near the end, clearly marked. The rest of this is the debugging guide I wish existed the last three times someone hit these errors.

If you run wkhtmltopdf in containers, you have probably met at least one of these three errors:

sh: /usr/local/bin/wkhtmltopdf: not found        # Alpine
wkhtmltox : Depends: libssl1.1 but it is not installable
E: Unable to locate package wkhtmltopdf          # Ubuntu 24.04 / Debian 13

All three have the same root cause: the project is archived (January 2023, repository read-only) and the last official packages were built in May 2023 — release 0.12.6.1-3, whose newest targets are Debian 12 (bookworm) and Ubuntu 22.04 (jammy). The distros kept moving; the binaries stopped. Here is what each error actually means, the recipe that still works in 2026, and the honest exits.

Error 1: `not found` on Alpine — it's not about PATH

The confusing part: the file is there, ls sees it, and the shell still says not found. That message comes from the kernel failing to load the binary's interpreter: official wkhtmltopdf builds link against glibc, Alpine ships musl, and the referenced dynamic loader (/lib64/ld-linux-x86-64.so.2) does not exist on Alpine. ldd /usr/local/bin/wkhtmltopdf shows it immediately.

There is no supported way around it on Alpine today: the distro dropped its wkhtmltopdf package years ago (nothing in current stable), and gcompat shims are a lottery with a binary this large. If the container must run wkhtmltopdf, don't build it on Alpine — that fight is not worth the ~50 MB you save.

Error 2: `Depends: libssl1.1` — you're installing a 2020 build on a 2023+ distro

The widely-copied Dockerfiles fetch wkhtmltox_0.12.6-1.*.deb, which links OpenSSL 1.1. Debian 12, Ubuntu 22.04+ and everything after ship OpenSSL 3 and removed libssl1.1 from the archives, so the dependency is unresolvable. (Pinning an EOL base image or hand-installing an EOL libssl to work around it means running an archived renderer on top of an unpatched TLS stack — please don't.)

The fix is simply the last release, which was built against OpenSSL 3 for bookworm and jammy.

The recipe that still works in 2026

FROM debian:bookworm-slim

ARG WKHTML_VERSION=0.12.6.1-3
RUN set -eux; \
    arch="$(dpkg --print-architecture)"; \
    apt-get update; \
    apt-get install -y --no-install-recommends curl ca-certificates; \
    curl -fsSLo /tmp/wkhtmltox.deb \
      "https://github.com/wkhtmltopdf/packaging/releases/download/${WKHTML_VERSION}/wkhtmltox_${WKHTML_VERSION}.bookworm_${arch}.deb"; \
    apt-get install -y --no-install-recommends /tmp/wkhtmltox.deb; \
    rm -f /tmp/wkhtmltox.deb; rm -rf /var/lib/apt/lists/*

# Fonts are on you: the image has almost none, and missing glyphs render as tofu.
RUN apt-get update && apt-get install -y --no-install-recommends \
      fontconfig fonts-dejavu-core fonts-noto-core fonts-noto-cjk \
    && rm -rf /var/lib/apt/lists/*

Notes that save an afternoon:

dpkg --print-architecture makes the same Dockerfile work on amd64 and arm64 — 0.12.6.1-3 ships both for bookworm and jammy.
Fonts: wkhtmltopdf uses system fonts via fontconfig. Add the font packages your documents actually need (the Noto families cover most scripts); re-check any non-Latin text after every base-image change.
Security: CVE-2022-35583 (SSRF through rendered content) is permanently unfixed. Never feed wkhtmltopdf untrusted HTML, and treat the container as hostile: no metadata endpoint access, egress restricted.

Error 3: Ubuntu 24.04, Debian 13, next year's anything

There is no build for noble, trixie, or anything newer — and there never will be. The bookworm/jammy debs may keep installing on newer bases for a while if the dependency chain happens to align, but every base-image bump is now a gamble against a binary from 2023. This is the actual signal to plan the migration rather than the next workaround.

The exits, briefly

I wrote a full decision tree in the migration field guide (including where each alternative beats everything else); the short version for container people:

Headless Chromium in your stack — Puppeteer/Playwright (page.pdf()), or Gotenberg as a ready-made sidecar container when you want an HTTP API without writing the browser management yourself.
WeasyPrint — if your documents are print-CSS shaped (invoices, statements) and don't run JavaScript; no browser process at all.
A hosted rendering API — when you'd rather ship an HTTP call than a browser fleet. Disclosure: this category includes my product, PDFik. If the thing keeping you on wkhtmltopdf is the flags — scripts and wrappers that speak its CLI — the PDFik CLI has a compatibility mode that takes wkhtmltopdf's own command line, and its image is a few megabytes with no browser inside:

docker run --rm -e PDFIK_API_KEY -v "$PWD:/work" -w /work \
  ghcr.io/pdfik/cli wkhtmltopdf -s A4 --footer-center 'Page [page] of [topage]' \
  https://example.com report.pdf

Every flag is mapped, accepted-with-a-warning, or refused with a reason — never silently ignored (flag-by-flag tables, option mapping). Rendering happens in our cloud on sandboxed Chromium, so the same honest caveat applies as to every hosted option: wrong for air-gapped setups, and your golden files need re-approval because the engine is not WebKit.

Package availability, archive status and CVE status last verified: 2026-08-27. If something here has rotted, tell me and I'll fix it.

wkhtmltopdf is archived with an open CVE — a field guide to moving off it

Vitalii Nemudryi — Wed, 26 Aug 2026 16:25:33 +0000

Disclosure up front: I'm Vitalii, founder of PDFik, a hosted
URL/HTML-to-PDF API. It appears below as one option among several — including the ones that
compete with it. Where a competitor is the better fit, I say so.

For a decade, wkhtmltopdf was the default answer to "how do I turn HTML into a PDF from my
backend?" — one static binary, no browser to babysit, a flag for everything. Most invoice,
report and ticket generators older than five years have it somewhere in their dependency tree.

Three facts changed that:

The project is archived. The GitHub repository was archived on January 2, 2023 and is read-only: no maintainers, no releases, no security patches — ever.
There is an unpatched vulnerability. CVE-2022-35583 (SSRF via rendered content) will never be fixed upstream. If your scanner flags it, there is no "upgrade to version X" remediation — the remediation is migration.
The packaging is rotting. The engine is a patched Qt WebKit from another era: modern CSS (grid, flexbox gaps, custom properties) silently misrenders, distros have been dropping the package, official builds don't cover current Debian/Ubuntu releases or arm64 well, and Docker images increasingly rely on third-party rebuilds of an unmaintained binary.

None of this means your PDFs stop rendering tomorrow. It means every new deployment target,
every security audit, and every CSS feature your designers use widens the gap. Here is the
decision tree I'd use to close it.

First, inventory what wkhtmltopdf actually does for you

Before comparing engines, grep your codebase for the flags you really use. In practice most
setups boil down to a handful:

You use	You need from a replacement
`--header-html` / `--footer-html`, page numbers	header/footer templates with page variables
`--margin-*`, `--orientation`, `--page-size`	standard page options (every option below has these)
`--print-media-type`	print-CSS support (`@page`, `page-break-*`)
`--javascript-delay`, `--window-status`	an explicit "wait until ready" mechanism
`--cookie`, `--custom-header`	authenticated fetching of the source page
`--toc`, `--outline`	PDF outline/bookmarks — check carefully, this is the weakest spot everywhere
stdin/stdout piping in a worker	either a library call or an API client

Two honest warnings apply to every path below: no Chromium-based engine reproduces
wkhtmltopdf output pixel-for-pixel (different engine, different line breaking, different
font fallback — you will re-approve golden files), and --toc/--outline have no
first-class Chromium equivalent (you rebuild outlines with a post-processing step or live
without them).

Path 1 — in-process library: WeasyPrint

If your documents are print-oriented (invoices, contracts, statements), your templates don't
run JavaScript, and you're on Python — WeasyPrint is the closest
thing to a spiritual successor: a real @page-first CSS engine, no browser process at all,
excellent page-break control, actively maintained.

Choose it when: print CSS is enough, no JS charts, Python stack, documents must not leave your infrastructure.
Walk away when: templates depend on JavaScript rendering (Chart.js, React-rendered markup) or you need the page to look exactly like it does in a browser.

The commercial sibling of this category is PrinceXML (and DocRaptor,
the hosted API built on it) — the strongest print-CSS engine on the market and the reference
choice when compliance-grade, print-perfect documents justify the price.

Path 2 — DIY headless Chromium: Playwright or Puppeteer

page.pdf() in Playwright / Puppeteer gives
you a modern engine, full JS execution, and total control. The code is five lines; the
operations are not: you now run a browser fleet. Zombie processes, memory ceilings per tab,
crash-looping renderers under load, sandboxing (seccomp/user namespaces if you take isolation
seriously), font packages in the image, timeouts, and scaling the pool — all yours.

Choose it when: you already operate containers comfortably, render volume is modest or bursty-but-internal, and you want zero per-document vendor cost.
Walk away when: PDF generation is a side feature and you'd rather not own a browser farm's pager duty.

Path 3 — self-hosted rendering API: Gotenberg

Gotenberg wraps Chromium (and LibreOffice for office formats) in a
Docker container with a clean HTTP API. You keep data on your infrastructure and get out of
the "manage Playwright yourself" business; you still own capacity planning, upgrades and
availability.

Choose it when: documents must stay in your VPC but you want an API, not a library.
Walk away when: you don't want to run and scale the container at all.

Path 4 — hosted APIs

If rendering is not your core business, a hosted API turns the whole problem into an HTTP
call. The market is healthy — a few honest reference points, all with published pricing:

DocRaptor — PrinceXML engine, the print-CSS gold standard, SOC 2 / HIPAA-BAA posture; documents can be very large. The established choice for compliance-heavy document generation.
PDFShift, Api2Pdf, PDFMonkey and others — Chromium-based hosted rendering with different pricing shapes (per-document, per-credit, template-first workflows). Worth shortlisting all three; which wins depends on your volume curve.
PDFik — my product, so discount accordingly. The design bet is async-first: you POST a URL or HTML, get a job_id, and receive an HMAC-signed webhook when the file is ready (polling and downloads exist too), with a free test mode that runs the full pipeline without touching your quota. There's a flag-by-flag wkhtmltopdf migration map that covers the table above in detail — including the places where wkhtmltopdf still wins. If what you actually want is to keep your existing wkhtmltopdf command lines, see path 5 below.

When is a hosted API simply wrong? Air-gapped environments, documents that legally may not
leave your infrastructure, or rendering volumes so high that per-document pricing can't beat
your marginal server cost. Those cases belong to paths 1–3.

Path 5 — keep the wkhtmltopdf interface, swap the engine: `pdfik wkhtmltopdf`

Full disclosure again: this one is mine too. Sometimes the blocker is not the engine but
the interface — hundreds of lines of shell, cron jobs and wrappers (pdfkit, wicked_pdf)
that all speak wkhtmltopdf's flags, and nobody wants to rewrite them just to retire a
binary. The PDFik CLI ships a compatibility mode that
takes wkhtmltopdf's own command line:

alias wkhtmltopdf='pdfik wkhtmltopdf'
wkhtmltopdf -s A4 -O Landscape --footer-center 'Page [page] of [topage]' https://example.com out.pdf

Every wkhtmltopdf flag is either mapped to the API, accepted with a warning (it has no
effect in this pipeline), or refused with a reason (it would silently change your output)
— never ignored. --version and -h answer the way wrappers expect, so pdfkit and
wicked_pdf keep working unmodified. The CLI itself is one static binary
(Linux/macOS/Windows, MIT, open source), also on Docker as ghcr.io/pdfik/cli; the
flag-by-flag tables live in the repo's
COMPATIBILITY.md.

Be clear about what this is: rendering happens in PDFik's cloud, so this is path 4 wearing
a familiar face — you need network access and an API key, and it is wrong for air-gapped
environments for the same reasons. The engine is sandboxed Chromium, not WebKit, so the
golden-files warning above applies in full. And --toc/--outline are refused, not
emulated — the honest answer from the inventory table stands here too.

Choose it when: the wkhtmltopdf interface is load-bearing (scripts, wrappers, colleagues' muscle memory) and hosted rendering is acceptable.
Walk away when: documents may not leave your infrastructure — that is paths 1–3.

The migration checklist (whatever you pick)

Golden files first. Render your 10 ugliest real documents on the old and new engine, diff visually, and get sign-off before touching production code paths.
Fonts. wkhtmltopdf used system fonts; containers and APIs won't have them by accident. Embed via @font-face or install them explicitly, then re-check non-Latin text.
Page breaks. Replace page-break-* hacks tuned for WebKit with standard break-inside: avoid / @page rules and re-test tables that span pages.
Readiness signal. Replace --javascript-delay guesswork with an explicit wait (a selector, window-status-style flag, or your engine's network-idle event).
Headers/footers. Rebuild --header-html as the engine's header/footer template and re-verify page numbering.
Outline/TOC. If you used --toc, decide now: post-process the PDF to rebuild bookmarks, or drop the feature consciously.
Timeouts and size limits. Async pipelines and APIs enforce both; find your P99 render time and largest document before your users do.
Keep the old binary in CI for one release as a fallback renderer behind a flag — migrations get reverted for boring reasons.

TL;DR decision tree

Print-CSS documents, no JS, Python → WeasyPrint (or PrinceXML/DocRaptor when budget allows).
Want full control and don't mind operating browsers → Playwright/Puppeteer.
Data must stay home, but you want an API → Gotenberg.
Want it to be someone else's pager → hosted API (DocRaptor for print/compliance; PDFShift/Api2Pdf/PDFMonkey/PDFik for Chromium-based rendering — pick by pricing shape and workflow; mine is the async/webhook-first one).
Scripts and wrappers full of wkhtmltopdf flags you'd rather not touch → pdfik wkhtmltopdf (compatibility mode of my CLI — hosted rendering behind the old interface).

Archive status and CVE status last verified: 2026-08-26. If something above is outdated,
tell me and I'll fix it.