Gotenberg releases

Breaking Changes & Security Fixes ⚠️

• Reverted SSRF defaults (breaking vs 8.31.0). 8.31.0 blocked private-IP destinations by default, which broke deployments running Gotenberg inside a private network. 8.32.0 restores the 8.30.x permissive defaults. Operators with internet-facing APIs opt into the strict posture via the new flags below.

• Rejected file:// at /forms/chromium/convert/url. Submitting url=file:///tmp/... used to let an unauthenticated caller enumerate the request working directory and read other in-flight uploads as rendered PDFs. The route now returns HTTP 400 for any file:// URL.

• Required uploaded file for image / pdf stamp and watermark sources. Twelve callsites accepted stampSource=pdf or watermarkSource=pdf with an expression pointing at any path the Gotenberg process could open, even when no file was uploaded. Handlers now return HTTP 400 unless the caller uploaded a matching file.

• Scoped file:// sub-resources to the request working directory. Crafted HTML could reference another request's file:///tmp/<reqdir>/.... The CDP request handler now restricts file:// sub-resources to the current request's directory. /convert/url and /screenshot/url reject every file:// sub-resource outright.

• Hardened Chromium against DNS rebinding. A short-TTL DNS authority could return a public IP at validation and a private IP at connect. A loopback HTTP / CONNECT proxy now sits between Chromium and the network, resolves DNS once, and pins the dial to the resolved IP. Skipped when --chromium-proxy-server or --chromium-host-resolver-rules is set.

• Filtered LibreOffice outbound fetches through a proxy. Uploaded OOXML, RTF, and ODF files can embed external URLs that LibreOffice's libcurl resolves below every Go-side SSRF filter. LibreOffice now routes every outbound fetch through an in-process forward proxy on the same gotenberg.DecideOutbound path Chromium and webhook delivery use. See the four new flags below.

• Recovered webhook async panics. High-concurrency webhooks could panic the async goroutine and crash the whole process. The goroutine now snapshots the request context and recovers any future panic through the existing error path.

New Features

• LibreOffice outbound URL filtering. Four flags mirror the Chromium and webhook layout: --libreoffice-allow-list, --libreoffice-deny-list, --libreoffice-deny-private-ips, --libreoffice-deny-public-ips. All default permissive.

• IP-class filtering on four modules. chromium, webhook, api-download-from, and libreoffice each accept matching deny-private-ips and deny-public-ips flags. All default to false.

| Flag | What it does |
| -------------------------------------- | --------------------------------------------------------------------------- |
| --chromium-deny-private-ips | Reject Chromium navigations and sub-resources resolving to a non-public IP. |
| --chromium-deny-public-ips | Reject Chromium navigations and sub-resources resolving to a public IP. |
| --webhook-deny-private-ips | Reject webhook URLs (success, error, events) resolving to a non-public IP. |
| --webhook-deny-public-ips | Reject webhook URLs resolving to a public IP. |
| --api-download-from-deny-private-ips | Reject downloadFrom URLs resolving to a non-public IP. |
| --api-download-from-deny-public-ips | Reject downloadFrom URLs resolving to a public IP. |
| --libreoffice-deny-private-ips | Reject LibreOffice outbound fetches resolving to a non-public IP. |
| --libreoffice-deny-public-ips | Reject LibreOffice outbound fetches resolving to a public IP. |

A URL matching --*-allow-list skips the IP-class check. A URL matching --*-deny-list is always rejected. Setting both deny-private-ips=true and deny-public-ips=true rejects every URL unless the allow-list matches.

Bug Fixes

• Charts print as blank rectangles (#1531, #1532, #1534, #1535): chromedp v0.15.0 suspended the BeginFrame-driven callback dispatch loop under emulatedMediaType=print. requestAnimationFrame, ResizeObserver, IntersectionObserver, CSS transitionend, and CSS animationend all stopped firing. Pinning chromedp back to v0.14.2 restores native dispatch.

• LibreOffice cached an unrecoverable first-start error (#1538): A short --libreoffice-start-timeout timed out the first request, then every subsequent request returned the same cached error until the container restarted. The lazy-start path now retries on failure.

Chore

• Updated pdfcpu to v0.12.0.
• Switched metadata read/write to direct exiftool invocation. Removes the GPL-3.0 go-exiftool dependency.
• Bumped Go to 1.26.2.
• Updated Go dependencies.

Thanks

Thanks to @Jalliuz (#1527) for reporting the 8.31.0 sub-resource regression. @notscottsmith (#1531), @spoltix (#1532), @rdelott-work (#1534), and @sillyas2010 (#1535) narrowed down the chromedp print-mode regression. @sillyas2010 also published the reproducer that pinned the bisect. @JeremyReist2 (#1536) flagged the go-exiftool GPL-3.0 license. @doronbehar (#1537) requested the pdfcpu upgrade. @mlafon (#1538) reported the LibreOffice supervisor cached-error bug.

Breaking Changes & Security Fixes ⚠️

• Stopped publishing thecodingmachine/gotenberg images. Pull from gotenberg/gotenberg instead.
• SSRF hardening (breaking). Resolves outbound URLs (Chromium asset fetches, webhook delivery, download-from) and rejects non-public addresses: loopback, RFC1918, link-local, unspecified, multicast, IPv6 unique-local, IPv4-mapped IPv6. Pins the dial to the validated IP to prevent DNS rebinding.
• Defaulted webhook deny list (breaking). --webhook-deny-list now defaults to a regex blocking loopback, RFC1918, link-local, and IPv6 unique-local ranges. Override the flag to call internal hosts.
• Sanitized ExifTool metadata (breaking for System: tags). Strips control characters and line breaks from /forms/pdfengines/metadata/write payloads. Drops System:-prefixed tags. Blocks argument smuggling and filesystem pseudo-tag abuse.

New Features

• Embed files metadata. Adds embedsMetadata to every route accepting embeds (Chromium HTML/URL/Markdown, LibreOffice convert, PDF Engines merge/split/embed). Pass a JSON object keyed by filename with per-file fields (mimeType, relationship, etc.) - thanks @Jean-Beru!

Bug Fixes

• Pinned Chromium to v146 on ppc64le to work around an upstream regression.

Deprecated Flags

| Old | New |
| ---------------------------- | ---------------------- |
| --webhook-error-allow-list | --webhook-allow-list |
| --webhook-error-deny-list | --webhook-deny-list |

Old flags still work.

Chore

• Updated Go dependencies.

Another release, another bug fixes 🫥

Bug Fixes

• chromium only variants now start correctly - thanks @agross!
• Re-added cURL for orchestrators health check - thanks @budivoogt, @gertjanstulp and @jfisbein!

New Features

Docker Image Variants

• Chromium-Only Image (gotenberg/gotenberg:8.30.0-chromium): Drops LibreOffice, python3, and hyphenation packages. ~30% smaller than the full image.
• LibreOffice-Only Image (gotenberg/gotenberg:8.30.0-libreoffice): Drops Chromium and its dependencies. ~38% smaller than the full image.

Pick the variant that matches your workload. The full image (gotenberg/gotenberg:8.30.0) still ships everything.

Leaner Docker Image

The full image is ~13% smaller than 8.29.0. The font stack was simplified from 30+ packages down to 8, covering Latin, Greek, Cyrillic, CJK, and most world scripts through Noto, plus color emoji.

| Package | Coverage |
| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fonts-noto-core | Arabic, Bengali, Devanagari, Ethiopic, Georgian, Gujarati, Gurmukhi, Hebrew, Kannada, Khmer, Lao, Malayalam, Myanmar, Sinhala, Tamil, Telugu, Thai, and more |
| fonts-noto-cjk | Chinese, Japanese, Korean |
| fonts-noto-color-emoji | Color emoji |
| fonts-dejavu | Latin, Greek, Cyrillic |
| fonts-crosextra-carlito | Metric-compatible with Calibri |
| fonts-crosextra-caladea | Metric-compatible with Cambria |
| fonts-liberation | Metric-compatible with Arial, Times New Roman, Courier New |
| fonts-liberation2 | Updated Liberation metrics |

Microsoft Core Fonts (ttf-mscorefonts-installer) are not shipped due to licensing constraints. The image includes metric-compatible replacements instead: Carlito for Calibri, Caladea for Cambria, and Liberation for Arial, Times New Roman, and Courier New. These preserve document layout in most cases.

Installing Additional Fonts

Build a custom Dockerfile to add fonts. Common scenarios:

Microsoft Core Fonts (you accept the Microsoft EULA):

FROM gotenberg/gotenberg:8

USER root

RUN echo "deb http://deb.debian.org/debian trixie contrib non-free" \
      > /etc/apt/sources.list.d/contrib.list \
    && echo "ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true" \
      | debconf-set-selections \
    && apt-get update -qq \
    && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends \
         ca-certificates \
         wget \
         ttf-mscorefonts-installer \
    && rm -rf /var/lib/apt/lists/*

USER gotenberg

Specialized script fonts for richer glyph sets, better hinting, or traditional typefaces beyond the basic Noto coverage:

| Script | Package |
| :----------------- | :--------------------- |
| Arabic (Naskh) | fonts-hosny-amiri |
| Bengali | fonts-beng |
| Devanagari (Hindi) | fonts-sarai |
| Ethiopic | fonts-sil-abyssinica |
| Gujarati | fonts-samyak-gujr |
| Gurmukhi (Punjabi) | fonts-lohit-guru |
| Hebrew | culmus |
| Kannada | fonts-lohit-knda |
| Malayalam | fonts-samyak-mlym |
| Myanmar | fonts-sil-padauk |
| Sinhala | fonts-lklug-sinhala |
| Tamil | fonts-samyak-taml |
| Telugu | fonts-telu |
| Thai | fonts-thai-tlwg |

FROM gotenberg/gotenberg:8

USER root

RUN apt-get update -qq \
    && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends \
        fonts-hosny-amiri \
        fonts-thai-tlwg \
    && rm -rf /var/lib/apt/lists/*

USER gotenberg

Webhook

• Gotenberg-Webhook-Error-Url Now Optional: When Gotenberg-Webhook-Events-Url is set, Gotenberg-Webhook-Error-Url is no longer required. Error handling flows through the events URL instead. Gotenberg-Webhook-Error-Url is deprecated but continues to work.

Bug Fixes

• ExifTool Tag Filtering: Case-insensitive comparison and expanded blocklist for ExifTool metadata filtering. Excludes additional system tags while preserving safe derived tags.
• Regex Timeout: Added timeout to regex evaluation to prevent ReDoS on malformed patterns.

Chore

• Updated Go dependencies.

Bug Fix (Chromium)

Assets were no longer being correctly loaded in HTML files. This is now fixed. Thanks @ARawles-GFSC for the heads up!

Security Fixes ⚠️

• ExifTool Arbitrary File Write: The /forms/pdfengines/metadata/write endpoint allowed users to pass FileName and Directory pseudo-tags in the metadata JSON, enabling file rename/move to arbitrary paths. User-supplied metadata is now filtered through a blocklist before being passed to ExifTool.
• Chromium file:// Sub-Resource Restriction: When converting HTML/Markdown via file://, sub-resources are now restricted to the request's working directory, preventing cross-request file access in /tmp.

New Features

OpenTelemetry

• Full OpenTelemetry Support: Distributed tracing, metrics export, and structured logging: all configurable via standard OTEL environment variables (OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER, OTEL_EXPORTER_OTLP_ENDPOINT, etc.). Every HTTP request gets a span. External tool calls (Chromium, LibreOffice, QPDF, pdfcpu, pdftk, ExifTool, webhook delivery, download-from) create child spans. Trace context is propagated to outbound HTTP calls via W3C headers.
• Structured Logging Migration: Migrated from custom logging module to slog-based structured logging with OTEL log bridge. Supports auto/JSON/text formats with optional GCP-compatible field names.
• Binary Path as Peer Service: server.address span attribute uses the actual binary path (e.g., /usr/bin/qpdf) instead of the software name.
• Telemetry Control for System Routes: New flags to disable telemetry for noisy system routes, all defaulting to disabled: --api-disable-root-route-telemetry, --api-disable-debug-route-telemetry, --api-disable-version-route-telemetry, --prometheus-disable-route-telemetry. The existing --api-disable-health-check-route-telemetry default changed from false to true.

Chromium

• Idle Shutdown: New --chromium-idle-shutdown-timeout flag (default: 0s, disabled) to automatically stop Chromium after a configurable idle period, reclaiming memory on low-traffic servers. The process re-launches lazily on the next request.
• Network Almost Idle Event: New skipNetworkAlmostIdleEvent form field (default: true). When set to false, Gotenberg waits for a "network almost idle" event (at most 2 open connections for 500ms) before conversion. This provides a middle ground between the existing skipNetworkIdleEvent (strict, 0 connections) and no wait at all — useful for pages with long-polling or analytics connections that never fully close.

LibreOffice

• PDF Viewer Preferences (#1316): 15 new form fields for controlling PDF viewer behavior: initialView, initialPage, magnification, zoom, pageLayout, firstPageOnLeft, resizeWindowToInitialPage, centerWindow, openInFullScreenMode, displayPDFDocumentTitle, hideViewerMenubar, hideViewerToolbar, hideViewerWindowControls, useTransitionEffects, openBookmarkLevels.
• Idle Shutdown: New --libreoffice-idle-shutdown-timeout flag (default: 0s, disabled), same behavior as Chromium.

Webhook

• Event Callbacks (#1473): New optional Gotenberg-Webhook-Events-Url header. When set, structured JSON events (webhook.success, webhook.error) are POSTed after each webhook operation, with correlationId and timestamp. Additive: existing Gotenberg-Webhook-Url and Gotenberg-Webhook-Error-Url continue to work unchanged.

Security & Networking

• Multiple URL Patterns: All allow/deny list flags (--chromium-allow-list, --chromium-deny-list, --webhook-allow-list, --webhook-deny-list, --webhook-error-allow-list, --webhook-error-deny-list, --api-download-from-allow-list, --api-download-from-deny-list) now accept multiple regex patterns via string slices. Existing single-value configurations continue to work.

Bug Fixes

• Chromium singlePage Margin Accounting (#1046): The singlePage option now correctly accounts for top/bottom margins when calculating page height, fixing content overflow on tall pages.
• Long Filename Support (#1500): Files with long names (166+ chars, especially with multi-byte UTF-8) no longer cause "File name too long" errors. Files are now stored on disk with UUID-based names while preserving original filenames for HTTP responses, archive entries, and JSON keys.

Deprecated Flags

| Old | New |
|-----|-----|
| --log-format | --log-std-format |
| --log-enable-gcp-fields | --log-std-enable-gcp-fields |
| --api-trace-header | --api-correlation-id-header |
| --api-disable-health-check-logging | --api-disable-health-check-route-telemetry |
| --prometheus-disable-route-logging | --prometheus-disable-route-telemetry |

All deprecated flags continue to work.

Chore

• Replaced go.uber.org/multierr with stdlib errors.Join.
• Added integration tests for Chromium screenshot routes (HTML, URL, Markdown).
• Added long filename integration tests across all PDF engine and conversion routes.
• Integration test retry mechanism: failed scenarios are automatically retried up to 3 times.
• Bumped actions/checkout to v6 in all GitHub Actions.

Thanks

Thanks to @dkrizic (#814) and @jbdelhommeau (#1489) for requesting OpenTelemetry/tracing support, @eht16 (#1316), @nh2 (#1023), @Frozen666 (#1046), @vofflan (#1500), @danxmoran (#1394), and @janaka (#1473) for their issue reports and feature requests!

This release represents a significant amount of work: OpenTelemetry integration, security fixes, new features, and hundreds of integration tests. If Gotenberg is useful to you or your team, please consider sponsoring the project. Your support helps keep development going.

New Features

PDF Engines

• Watermark: Added POST /forms/pdfengines/watermark route. Applies a watermark (behind page content) to one or more PDF files. Supports text, image, or pdf sources. Also available as optional form fields on Chromium, LibreOffice, merge, and split routes. Configurable via --pdfengines-watermark-engines (default: pdfcpu,pdftk).
• Stamp: Added POST /forms/pdfengines/stamp route. Applies a stamp (on top of page content) to one or more PDF files. Same source types and integration points as watermark. Configurable via --pdfengines-stamp-engines (default: pdfcpu,pdftk).
• Rotate: Added POST /forms/pdfengines/rotate route. Rotates pages by 90°, 180°, or 270° with optional page selection. Also available as optional form fields (rotateAngle, rotatePages) on all composite routes. Configurable via --pdfengines-rotate-engines (default: pdfcpu, pdftk).
• Bookmarks (Read): Added POST /forms/pdfengines/bookmarks/read route. Returns the hierarchical bookmark outline from one or more PDF files as JSON. Configurable via --pdfengines-read-bookmarks-engines (default: pdfcpu).
• Bookmarks (Write): Added POST /forms/pdfengines/bookmarks/write route. Accepts either a flat list (applied to all files) or a filename-keyed map. Configurable via --pdfengines-write-bookmarks-engines (default: pdfcpu, pdftk).
• Merge Bookmark Management: The merge route now supports a bookmarks form field for custom bookmarks with automatic page-offset shifting, and an autoIndexBookmarks option to extract and reindex existing bookmarks from input files.
• PDF/A & PDF/UA Compliance: Reordered the processing pipeline so that PDF/A and PDF/UA conversion runs after watermark, stamp, and flatten operations. Also reject incompatible combinations (e.g., PDF/A + encryption, PDF/A-1/2 + embeds) with a 400 Bad Request.

LibreOffice

• Native Watermarks: Added support for LibreOffice's built-in watermark rendering during PDF export via new form fields: nativeWatermarkText, nativeWatermarkColor, nativeWatermarkFontHeight, nativeWatermarkRotateAngle, nativeWatermarkFontName, and nativeTiledWatermarkText.

API

• Download From: Extended the downloadFrom JSON schema with a field property ("watermark", "stamp", "embedded", or "") to route downloaded files to the appropriate form field bucket. The existing embedded boolean is preserved for backward compatibility.

Chore

• Updated Chromium to 146.0.7680.153-1.
• Updated Go dependencies.

New Features

Chromium

• Concurrency Support: Re-introduced support for simultaneous conversions (up to 6 by default). Configurable via CHROMIUM_MAX_CONCURRENCY. Thanks @TomBrouws!
• Restart Threshold: Updated the default value for CHROMIUM_RESTART_AFTER to 100.
• Emulated Media Features: Added the emulatedMediaFeatures form field. This allows users to pass a JSON array to simulate specific CSS media features, such as prefers-color-scheme: dark or prefers-reduced-motion. Thanks @danxmoran!

Misc

• Timezone: The default timezone is now explicitly UTC and is visible in the debug route. This remains overridable via the TZ environment variable. Thanks @davpsh!

Bug Fixes

• PDF Engines: Resolved an issue where unnecessary derived tags were added when writing metadata. Thanks @znemoe!

Chore

• Updated Chromium to 145.0.7632.109.
• Updated LibreOffice to 26.2.0.
• Updated Go dependencies.
• Bumped Go version to 1.26.0.

New Features

Chromium

• New form field waitForSelector: as an alternative to waiting on an expression, this allows users to wait for a specific node matching a selector to become visible in the HTML / at the remote URL before converting to PDF - thanks @danxmoran!
• New form field ignoreResourceHttpStatusDomains: exclude resources from failOnResourceHttpStatusCodes checks based on their hostname - thanks @frostmark!

Prometheus

• New flag --prometheus-metrics-path to customize the metrics route path - thanks @davpsh!

Bug Fix

• Gotenberg does not ignore anymore client disconnections, closing resources early - thanks @romanek-adam-b2c2!

Chore

• Updated Chromium to version 144.0.7559.96.
• Updated Go dependencies.
• Bumped Go to version 1.25.5 (thanks @jmendes-alto).