System Setup

Gutterpress does almost everything in-process. It needs only a Chromium-based browser to render PDFs, plus — for the optional PDF/X (CMYK) pre-print pipeline — Ghostscript and qpdf. This chapter explains what each tool is for, how to install it, and how the Docker image gives you the whole pipeline with nothing to install.

Quick Reference

Why so few tools? Page size, fonts, images/DPI, bookmarks, links, page labels, text density, structure, image color/alpha, and markdown/HTML/CSS linting all run in-process — no Poppler, ImageMagick, markdownlint-cli2, htmlhint, or stylelint to install. A plain RGB build needs only a browser; Ghostscript and qpdf exist solely to enable PDF/X checks and conversion.

Check your setup: gutterpress doctor

Before installing anything, run gutterpress doctor to see exactly what Gutterpress already found on your machine:

gutterpress doctor

It prints the Gutterpress version, your OS/architecture, the CLI config directory, and a table of every optional tool — found or missing, its resolved path, which features use it, and (for anything missing) the exact install command for your platform. Run it again after installing a tool to confirm it was picked up.

Easiest path: Docker (the whole PDF/X pipeline, nothing to install)

If you want a complete, validated, print-ready PDF/X without installing Ghostscript/qpdf/Chromium yourself, use the container — it bundles all three:

# One-off: build a print-ready PDF/X from a project in the current folder
docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" \
    ghcr.io/dimm-city/gutterpress \
    build my-book --out dist/my-book.pdf --format pdfx

This is also the recommended way to run the full pipeline in CI. See the Docker guide for the convenience alias, output ownership, and CI examples. The rest of this chapter covers installing the tools directly on your machine instead.

Install the tools on your machine

macOS

# Required — any one of these works
brew install --cask chromium
brew install --cask google-chrome
brew install chromium

# Recommended (needed for PDF/X)
brew install ghostscript

# Only for PDF/X (annotation stripping + PDF/X validation)
brew install qpdf

Windows

Install Chrome or Chromium from the official websites. For Ghostscript and other tools, use winget or Chocolatey:

winget install Ghostscript.Ghostscript
winget install qpdf.qpdf  # PDF/X only

Windows note: Gutterpress uses where instead of which to probe for tools. If you have busybox or other POSIX emulators installed, ensure where is the one on PATH.

Linux (Debian/Ubuntu)

# Required — any one works
sudo apt install chromium-browser
sudo apt install google-chrome-stable

# Recommended
sudo apt install ghostscript

# Only for PDF/X (annotation stripping + PDF/X validation)
sudo apt install qpdf

Linux (Fedora/RHEL)

sudo dnf install chromium ghostscript qpdf

Tool Details

Chrome / Chromium — required for PDF

Gutterpress launches a Chromium-based browser already on your machine and drives it over the DevTools protocol to render PDFs. It never downloads or bundles a browser. If no browser is found, you will see:

No Chrome / Chromium / Edge binary found. Gutterpress needs a Chromium-based
browser to render PDFs.

Resolution order (Gutterpress checks these in sequence — first match wins):

1. The CHROMIUM_PATH environment variable (PUPPETEER_EXECUTABLE_PATH is still accepted as a deprecated alias; CHROMIUM_PATH is checked first)
2. Standard install locations for Chrome, Chromium, Edge, and Brave on your OS (the paths installed by the commands above)
3. A PATH probe (which / where.exe) for Chrome, Chromium, Edge, Brave, Vivaldi, Opera, and their platform-specific variants

Fix: install Chrome, Chromium, Edge, Brave, Vivaldi, or Opera normally, or set CHROMIUM_PATH=/path/to/your/browser if it's in a non-standard location. The Gutterpress desktop app includes its own browser and needs no separate browser installation.

Ghostscript — recommended for PDF/X

Used for CMYK conversion, ICC profiles, TAC validation, and PDF/X-1a compliance. Required if building with --format pdfx.

Gutterpress checks GHOSTSCRIPT_PATH first, then the command names available on PATH (gs on macOS/Linux; gswin64c, gswin32c, or gs on Windows). On Windows it also detects versioned installs under the conventional Program Files\gs\gs*\bin directories, so the standard installer works without a hand-made gs alias.

Fix: Install Ghostscript normally, or set GHOSTSCRIPT_PATH to its command-line executable when it lives in a non-standard location.

qpdf — PDF/X only

Required for the stripAnnotations step in the PDF/X pipeline, and for the PDF/X-specific validation checks (pdf.print.pdfx-markers, pdf.print.pdfx-metadata). Not needed for standard PDF output or for general PDF validation — those now use the bundled PDF.js engine.

warn: Tool "qpdf" not found — skipping: pdf.print.pdfx-markers, pdf.print.pdfx-metadata

This is a warning, not an error — the build succeeds, but those PDF/X checks are skipped.

PDF validation — built in (no Poppler)

Page size, bleed boxes, embedded fonts, image resolution/DPI, bookmarks, TOC links, cross-references, page labels, rasterized-page detection, text density, layout variance, and structural parsing all run in-process via a bundled PDF.js engine (the unpdf package). Poppler (pdfinfo, pdffonts, pdfimages, pdftotext) is no longer used or required. These checks run everywhere, including from the standalone binary, with zero system tools.

Fidelity note: structural validation is a "does it parse cleanly" gate rather than a deep qpdf --check, and image DPI is derived from the rendered placed size (best-effort).

Image asset checks — built in (no ImageMagick)

Image resolution (DPI), color space, and alpha-channel checks read PNG/JPEG/TIFF headers in-process — ImageMagick (identify) is no longer used or required. These run everywhere, including from the standalone binary.

Source linting — built in

Markdown linting (source.markdownlint) and HTML linting (source.htmlhint) run in-process using the bundled markdownlint and htmlhint libraries. No markdownlint-cli2 or htmlhint CLI install is required — these checks run everywhere, including from the standalone binary. Disable either in the manifest if not needed, or point them at a config file:

validate:
  source:
    markdownlint: false          # or ".markdownlint.yaml" to use a config
    htmlhint: false              # or ".htmlhintrc"

Markdown linting auto-detects .markdownlint.{yaml,yml,json,jsonc} (and the .markdownlint-cli2.{yaml,jsonc} variants) in the source directory; HTML linting auto-detects .htmlhintrc.

CSS print-safety linting — built in (no stylelint)

The source.stylelint check (gutterpress validate, and gutterpress build's pre-build validation) checks CSS for print-safety issues (remote URLs, rasterizing effects) using Gutterpress's own postcss-based checks. stylelint is not used or required — it can't be bundled into the bun build --compile binary, so these checks run in-process everywhere, including from the standalone binary.

Configuration

Environment variables

qpdf has no path-override environment variable; add a non-standard install to PATH.

The CLI config directory is %APPDATA%\gutterpress on Windows and $XDG_CONFIG_HOME/gutterpress (or ~/.config/gutterpress) on macOS and Linux. Diagnostics report this existing location; Gutterpress does not move credentials when reporting it.

Manifest tool paths

There is no manifest key for overriding tool binary paths — no tools: block, no chromePath/ghostscriptPath options. Use the environment variables above (Chromium and Ghostscript) or PATH instead.

Troubleshooting

Ghostscript executable not found

Ghostscript was not found in the locations above. Install it, set GHOSTSCRIPT_PATH, or verify the command is on PATH:

gs --version

No Chrome / Chromium / Edge binary found

No browser was found. Install Chrome, Chromium, Edge, Brave, Vivaldi, or Opera, or set CHROMIUM_PATH to an existing binary. Gutterpress cannot download one for you — see "Chrome / Chromium — required for PDF" above. Alternatively, use the desktop app, which includes its own browser.

spawn qpdf ENOENT during PDF/X build

qpdf is not installed. Required for --format pdfx. Install it from your package manager.

Some validation checks reported as "skipped"

General PDF, source, and image-asset checks run in-process and never skip. Only the PDF/X checks (need qpdf) and ink-coverage (needs gs) can be skipped — install the relevant tool to enable them.

A specific check still fails after installing its tool

Restart the terminal to pick up the updated PATH. If the tool is in a non-standard location, set CHROMIUM_PATH (Chromium), set GHOSTSCRIPT_PATH (Ghostscript), or add qpdf to PATH.

Roadmap

Shipped

• Chrome / Chromium PDF rendering over the DevTools protocol (no browser driver dependency)
• Ghostscript PDF/X conversion
• qpdf annotation stripping + PDF/X validation
• In-process PDF validation via bundled PDF.js (replaced Poppler)
• In-process markdown/HTML linting (replaced markdownlint-cli2/htmlhint)
• In-process image asset checks (replaced ImageMagick identify)

Planned (Tier 2)

• Native PDF font subsetting (reduce file size without Ghostscript)
• Integrated image optimization pass

Future / situational (Tier 3)

• ICC profile embedding for specific print vendors
• Automated ink coverage correction