Run LibreOffice Headless in Docker for PDF Conversion

Yes. For one-off document conversions, build a small Docker image with LibreOffice installed and run soffice --headless with --convert-to. Mount the input directory read-only and a separate output directory with write access so the PDF appears on your host. This example uses a Debian-based image and converts one DOCX file to PDF; it does not expose LibreOffice as a network service.

What does headless mode do, and when is Docker useful?

Headless mode starts LibreOffice without its graphical interface. LibreOffice documents this mode for command-line and API-controlled use, and its command-line options support file conversion with an output directory. Docker packages the application and its dependencies so a script or workstation can run the same container image without installing the desktop suite on the host.

This pattern works well for local batch jobs, CI tasks, or a backend worker that receives a file and saves a converted result. A plain headless container is not, by itself, an HTTP conversion API: it listens on no port and accepts no web uploads. If you need a persistent service, put an API and job queue around the conversion process and add request validation, timeouts, file-size limits, and isolation.

1. Create the input and output folders

On a Linux or macOS host using Bash or a similar shell, create a project folder with separate directories. Put the source document in input and leave output empty for the first run:

mkdir -p lo-work/input lo-work/output
cp report.docx lo-work/input/
cd lo-work

The Docker commands below use Unix-style paths and shell syntax. On Windows, adjust the host path syntax for PowerShell or Command Prompt and make sure Docker Desktop is allowed to share the drive containing these folders.

2. Build an image with LibreOffice

Create a file named Dockerfile inside lo-work with this content:

FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
    libreoffice-writer fonts-liberation \
    && rm -rf /var/lib/apt/lists/*

ENTRYPOINT ["soffice"]

libreoffice-writer supplies Writer and the conversion filters needed for common word-processing formats. Add libreoffice-calc or libreoffice-impress if the container must convert spreadsheets or presentations. The font package is only a baseline; install the fonts your documents require and have rights to use, because missing fonts can change line wrapping and page breaks.

Build the image from the directory that contains the Dockerfile:

docker build -t lo-headless .

The example uses Debian Bookworm package names. Base-image tags and repository packages change over time; for a production build, choose a maintained base, rebuild it regularly for security updates, and pin the base image by digest if you need reproducible builds. Avoid installing packages from an unrelated repository just to match a tutorial.

3. Run LibreOffice with separate mounts

Start a disposable container and pass the conversion options after the image name. The input mount is read-only; only the output directory is writable. The --user option runs the process with your host user and group IDs on Linux, while HOME=/tmp gives LibreOffice a writable home. Adjust folder permissions if the host user cannot write to output.

docker run --rm \
  --user "$(id -u):$(id -g)" \
  --env HOME=/tmp \
  -v "$PWD/input:/input:ro" \
  -v "$PWD/output:/output" \
  lo-headless \
  --headless --nologo \
  -env:UserInstallation=file:///tmp/lo-profile \
  --convert-to pdf:writer_pdf_Export \
  --outdir /output \
  /input/report.docx

--headless suppresses the GUI, --convert-to pdf:writer_pdf_Export selects the PDF export filter, and --outdir directs the result to the mounted output folder. The unique user-profile path gives this process a writable LibreOffice configuration directory; if you run several conversions concurrently in one long-lived container, use a different profile path for each process.

Use --mount instead of -v if you prefer Docker’s more explicit mount syntax. Bind mounts are tied to paths on the Docker daemon’s host, and read-write mounts let container processes change host files. Keep mounts narrow, avoid mounting your home directory or Docker socket, and do not run a document-conversion worker with unnecessary privileges.

4. Confirm that the PDF was created

Check the host output directory after Docker exits:

ls -l output/
file output/report.pdf
test -s output/report.pdf

The PDF should exist and be nonempty. Open it in a PDF reader and check page count, tables, images, page breaks, and fonts before relying on it. A successful process exit does not prove that every element rendered as intended, especially when a document uses fonts or features unavailable in the container. Use a clean output directory or a new output filename for each run so an older PDF cannot be mistaken for the latest conversion.

What should I check if the conversion fails?

• No output file: confirm the source filename and container path, that input was mounted at /input, and that the host output directory is writable by the selected user.
• Profile or lock errors: confirm the -env:UserInstallation path is writable. Use a separate profile directory for each simultaneous LibreOffice process.
• Changed layout: install the needed fonts in the image and review the PDF. Rendering can differ from a desktop system because of font availability, export filters, and version differences.
• Docker mount error: verify both host directories exist before using -v or --mount, and verify that the daemon can access them.

For exact option behavior, see LibreOffice’s command-line parameter reference. Package names can be checked in the Debian Bookworm package listing for LibreOffice Writer. Docker’s official documentation explains bind mounts and the Dockerfile instructions.