This repository defines a set of Docker images for running LaTeX in containers, optimized for CI/CD workflows and local development. Built on Ubuntu 22.04 LTS, these images provide a stable and reliable foundation for LaTeX compilation.

The images come in several variants corresponding to TeX Live schemes, from minimal installations to complete distributions. The default scheme is full, which contains all packages for maximum compatibility.

If a package is missing, you can always use tlmgr to install it. Since the images are based on Ubuntu, system packages can be installed using apt-get.

The images use a layered architecture where each variant builds upon the previous one. For example, full adds packages to medium, which extends small, and so on. This approach optimizes storage space and build efficiency.

For a simple LaTeX compilation, assuming you have a file named main.tex in your current directory:

docker run --rm -v "$PWD:/src" -w /src -u "$UID:$GID" \
  dmgiulioromano/latex-docker-ubuntu:latest \
  latexmk -pdf -outdir=out -auxdir=out/aux main.tex

This command will:

• Mount your current directory to /src in the container
• Set the working directory to /src
• Run as your user to maintain file permissions
• Compile main.tex to PDF in the out directory

For continuous compilation during development:

docker run --rm -v "$PWD:/src" -w /src -u "$UID:$GID" \
  dmgiulioromano/latex-docker-ubuntu:latest \
  latexmk -pdf -pvc -outdir=out -auxdir=out/aux main.tex

The -pvc flag enables "preview continuously" mode, automatically recompiling when source files change.

For XeLaTeX compilation:

docker run --rm -v "$PWD:/src" -w /src -u "$UID:$GID" \
  dmgiulioromano/latex-docker-ubuntu:latest \
  latexmk -xelatex -outdir=out main.tex

For LuaLaTeX compilation:

docker run --rm -v "$PWD:/src" -w /src -u "$UID:$GID" \
  dmgiulioromano/latex-docker-ubuntu:latest \
  latexmk -lualatex -outdir=out main.tex

If you prefer not to use latexmk, you can run any LaTeX command directly:

docker run --rm -v "$PWD:/src" -w /src -u "$UID:$GID" \
  dmgiulioromano/latex-docker-ubuntu:latest \
  pdflatex main.tex

For complex build processes, you might need additional tools like make:

docker run --rm -v "$PWD:/src" -w /src -u "$UID:$GID" \
  dmgiulioromano/latex-docker-ubuntu:latest \
  sh -c "apt-get update && apt-get install -y make && make"

• -c - Clean auxiliary files
• -g - Force compilation even if no changes detected
• -silent - Suppress output except for errors
• -f - Force compilation even after errors
• -interaction=nonstopmode - Don't pause for errors

See the latexmk documentation for complete usage and options.

Stable versions follow the format <major>.<minor> (e.g., 2025.1), where:

• Major version: Corresponds to the TeX Live year
• Minor version: Image version within that TeX Live release

Stable versions provide:

• Tested and verified package sets
• Security updates and bug fixes
• Consistent package versions for reproducible builds

name: Compile LaTeX Document
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    container: dmgiulioromano/latex-docker-ubuntu:latest
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Compile LaTeX document
        run: latexmk -pdf -output-directory=dist main.tex

      - name: Upload PDF artifact
        uses: actions/upload-artifact@v4
        with:
          name: compiled-document
          path: dist/main.pdf

stages:
  - build

compile_latex:
  stage: build
  image: dmgiulioromano/latex-docker-ubuntu:latest
  script:
    - latexmk -pdf -output-directory=dist main.tex
  artifacts:
    paths:
      - dist/main.pdf
    expire_in: 1 week

# Run container interactively
docker run -it --rm -v "$PWD:/src" -w /src \
  dmgiulioromano/latex-docker-ubuntu:latest bash

# Inside container, install packages
tlmgr install <package-name>

# Update package database
tlmgr update --self

# Update all packages
tlmgr update --all

For optimized production images:

FROM dmgiulioromano/latex-docker-ubuntu:medium as builder
COPY . /workspace
WORKDIR /workspace
RUN latexmk -pdf main.tex

FROM ubuntu:latest
COPY --from=builder /workspace/main.pdf /output/

# Install system fonts
apt-get update && apt-get install -y fonts-liberation

# Or copy custom fonts
COPY fonts/ /usr/share/fonts/custom/
fc-cache -fv

Ensure you run with proper user permissions:

docker run --rm -v "$PWD:/src" -w /src -u "$(id -u):$(id -g)" \
  dmgiulioromano/latex-docker-ubuntu:latest latexmk -pdf main.tex

If compilation fails due to missing packages:

# Use a larger image variant
docker run --rm -v "$PWD:/src" -w /src \
  dmgiulioromano/latex-docker-ubuntu:full latexmk -pdf main.tex

# Or install the specific package
docker run --rm -v "$PWD:/src" -w /src \
  dmgiulioromano/latex-docker-ubuntu:latest \
  sh -c "tlmgr install <package-name> && latexmk -pdf main.tex"

For documents requiring specific fonts:

# Install additional font packages
docker run --rm -v "$PWD:/src" -w /src \
  dmgiulioromano/latex-docker-ubuntu:latest \
  sh -c "apt-get update && apt-get install -y fonts-<font-package> && latexmk -pdf main.tex"

Contributions are welcome! Please see our contributing guidelines for details on:

• Reporting issues
• Submitting pull requests
• Development setup
• Testing procedures

This project is licensed under the MIT License - see the LICENSE file for details.

This project is based on the excellent work by kjarosh/latex-docker, adapted for Ubuntu-based environments to provide better compatibility with certain LaTeX packages and system dependencies.

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 🐳 Docker Hub