Skip to content

armgit / manim

Public Imported from GitHub
0

A community-maintained Python framework for creating mathematical animations.

Make Docker image build robust against TeX mirror failures (#5095)

Benjamin Hackl78d47aec8c81
diff --git a/.dockerignore b/.dockerignore
index e19bacca9..73dc71e52 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -1,6 +1,8 @@
.git
# Development / test artifacts
+.venv
+.pytest_cache
__pycache__
**/__pycache__
*.pyc
diff --git a/.github/workflows/publish-docker.yml b/.github/workflows/publish-docker.yml
index 19bb4bb57..05f79ecc4 100644
--- a/.github/workflows/publish-docker.yml
+++ b/.github/workflows/publish-docker.yml
@@ -6,39 +6,118 @@ on:
- main
release:
types: [released]
+ pull_request:
+ paths:
+ - docker/**
+ - .dockerignore
+ - .github/workflows/publish-docker.yml
+ workflow_dispatch:
+
+# A newer push to main supersedes an older build still in progress, so an
+# outdated build can never overwrite `latest`.
+concurrency:
+ group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+ cancel-in-progress: true
+
+permissions:
+ contents: read
+
+env:
+ IMAGE: manimcommunity/manim
+ # Only pushes to main and releases publish to Docker Hub. Pull requests and
+ # manual runs on other branches only build and verify the image.
+ PUBLISH: ${{ github.event_name == 'release' || (github.event_name != 'pull_request' && github.ref == 'refs/heads/main') }}
jobs:
- docker-latest:
- runs-on: ubuntu-latest
- if: github.event_name != 'release'
+ build:
+ name: Build (${{ matrix.arch }})
+ runs-on: ${{ matrix.runner }}
+ timeout-minutes: 60
+ strategy:
+ fail-fast: true
+ matrix:
+ include:
+ - arch: amd64
+ platform: linux/amd64
+ runner: ubuntu-24.04
+ - arch: arm64
+ platform: linux/arm64
+ runner: ubuntu-24.04-arm
steps:
- - name: Set up QEMU
- uses: docker/setup-qemu-action@v4
+ - name: Checkout
+ uses: actions/checkout@v7
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v4
- name: Login to DockerHub
+ if: env.PUBLISH == 'true'
uses: docker/login-action@v4
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- - name: Build and push
+ - name: Build image
+ uses: docker/build-push-action@v7
+ with:
+ context: .
+ file: docker/Dockerfile
+ platforms: ${{ matrix.platform }}
+ load: true
+ tags: manim:verify
+ cache-from: type=gha,scope=docker-${{ matrix.arch }}
+ # Only publishing builds write the cache, so pull requests do not
+ # evict the cache that main and releases rely on.
+ cache-to: ${{ env.PUBLISH == 'true' && format('type=gha,scope=docker-{0},mode=max', matrix.arch) || '' }}
+
+ - name: Verify image
+ run: |
+ docker run --rm -v "$PWD/docker:/test:ro" manim:verify \
+ manim render -ql --media_dir /tmp/media /test/verify_image.py VerifyImage
+
+ # Reuses the layers built above; pushes an untagged image by digest.
+ # The publish job tags the per-platform digests as one image.
+ - name: Push image by digest
+ id: push
+ if: env.PUBLISH == 'true'
uses: docker/build-push-action@v7
with:
- platforms: linux/arm64,linux/amd64
- push: true
+ context: .
file: docker/Dockerfile
- tags: |
- manimcommunity/manim:latest
+ platforms: ${{ matrix.platform }}
+ outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true
+ cache-from: type=gha,scope=docker-${{ matrix.arch }}
- docker-release:
+ - name: Export digest
+ if: env.PUBLISH == 'true'
+ env:
+ DIGEST: ${{ steps.push.outputs.digest }}
+ run: |
+ mkdir -p "$RUNNER_TEMP/digests"
+ touch "$RUNNER_TEMP/digests/${DIGEST#sha256:}"
+
+ - name: Upload digest
+ if: env.PUBLISH == 'true'
+ uses: actions/upload-artifact@v7
+ with:
+ name: digest-${{ matrix.arch }}
+ path: ${{ runner.temp }}/digests/*
+ if-no-files-found: error
+ retention-days: 1
+
+ publish:
+ name: Publish multi-platform image
+ needs: build
+ if: github.event_name == 'release' || (github.event_name != 'pull_request' && github.ref == 'refs/heads/main')
runs-on: ubuntu-latest
- if: github.event_name == 'release'
+ timeout-minutes: 15
steps:
- - name: Set up QEMU
- uses: docker/setup-qemu-action@v4
+ - name: Download digests
+ uses: actions/download-artifact@v8
+ with:
+ path: ${{ runner.temp }}/digests
+ pattern: digest-*
+ merge-multiple: true
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v4
@@ -49,24 +128,15 @@ jobs:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- - name: Get Version
- id: create_release
- shell: python
- env:
- tag_act: ${{ github.ref }}
+ - name: Create and push manifest list
+ working-directory: ${{ runner.temp }}/digests
run: |
- import os
- ref_tag = os.getenv('tag_act').split('/')[-1]
- with open(os.getenv('GITHUB_OUTPUT'), 'w') as f:
- print(f"tag_name={ref_tag}", file=f)
+ tags=(-t "$IMAGE:latest")
+ if [ "$GITHUB_EVENT_NAME" = release ]; then
+ tags+=(-t "$IMAGE:stable" -t "$IMAGE:$GITHUB_REF_NAME")
+ fi
+ docker buildx imagetools create "${tags[@]}" \
+ $(printf "$IMAGE@sha256:%s " *)
- - name: Build and push
- uses: docker/build-push-action@v7
- with:
- platforms: linux/arm64,linux/amd64
- push: true
- file: docker/Dockerfile
- tags: |
- manimcommunity/manim:stable
- manimcommunity/manim:latest
- manimcommunity/manim:${{ steps.create_release.outputs.tag_name }}
+ - name: Inspect image
+ run: docker buildx imagetools inspect "$IMAGE:latest"
diff --git a/docker/Dockerfile b/docker/Dockerfile
index 7036c754a..463f1e28a 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -1,52 +1,113 @@
-# ── Stage 1: builder ─────────────────────────────────────────────────────────
-FROM python:3.14-slim AS builder
+# syntax=docker/dockerfile:1
-RUN apt-get update -qq \
- && apt-get install --no-install-recommends -y \
+ARG PYTHON_VERSION=3.14
+ARG UV_VERSION=0.13
+# TeX Live is pinned to the frozen final state of a past release ("tlnet-final"
+# in the historic archive), so the installation is identical on every build and
+# does not depend on the CTAN mirror rotation.
+ARG TL_YEAR=2025
+
+FROM ghcr.io/astral-sh/uv:${UV_VERSION} AS uv
+
+# ── Stage 1: TeX Live ────────────────────────────────────────────────────────
+# Independent of the Python base image and of the manim sources, so the build
+# cache for this (network-heavy) stage survives most changes.
+FROM debian:trixie-slim AS texlive
+
+ARG TL_YEAR
+# Tried in order; the first repository that completes the installation wins.
+ARG TL_REPOSITORIES="\
+https://ftp.tu-chemnitz.de/pub/tug/historic/systems/texlive/${TL_YEAR}/tlnet-final \
+https://mirrors.tuna.tsinghua.edu.cn/tex-historic-archive/systems/texlive/${TL_YEAR}/tlnet-final"
+
+RUN apt-get -o Acquire::Retries=5 update -qq \
+ && apt-get -o Acquire::Retries=5 install --no-install-recommends -y \
+ ca-certificates \
+ curl \
+ libfontconfig1 \
+ perl \
+ xz-utils \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY docker/texlive-profile.txt docker/texlive-packages.txt /tmp/
+
+# bin/linux is an architecture-independent link to bin/{x86_64,aarch64}-linux.
+RUN set -eu; \
+ packages="$(grep -v -e '^#' -e '^[[:space:]]*$' /tmp/texlive-packages.txt)"; \
+ for repo in ${TL_REPOSITORIES}; do \
+ echo "==> Installing TeX Live ${TL_YEAR} from ${repo}"; \
+ rm -rf /tmp/install-tl /usr/local/texlive; \
+ mkdir -p /tmp/install-tl; \
+ if curl -fsSL --retry 5 --retry-all-errors --connect-timeout 20 --max-time 300 \
+ -o /tmp/install-tl-unx.tar.gz "${repo}/install-tl-unx.tar.gz" \
+ && tar -xzf /tmp/install-tl-unx.tar.gz -C /tmp/install-tl --strip-components=1 \
+ && timeout 30m /tmp/install-tl/install-tl \
+ --profile=/tmp/texlive-profile.txt --repository "${repo}" \
+ && timeout 30m /usr/local/texlive/bin/*-linux/tlmgr \
+ --repository "${repo}" install ${packages}; \
+ then \
+ installed=1; \
+ break; \
+ fi; \
+ echo "==> Installation from ${repo} failed, trying the next repository" >&2; \
+ done; \
+ test "${installed:-0}" = 1 || { echo "==> All TeX Live repositories failed" >&2; exit 1; }; \
+ ln -s "$(basename /usr/local/texlive/bin/*-linux)" /usr/local/texlive/bin/linux; \
+ rm -rf /tmp/install-tl /tmp/install-tl-unx.tar.gz \
+ /usr/local/texlive/install-tl.log /usr/local/texlive/texmf-var/web2c/*.log
+
+ENV PATH=/usr/local/texlive/bin/linux:$PATH
+RUN latex --version | head -n 1 && dvisvgm --version
+
+# ── Stage 2: Python builder ──────────────────────────────────────────────────
+FROM python:${PYTHON_VERSION}-slim AS builder
+
+RUN apt-get -o Acquire::Retries=5 update -qq \
+ && apt-get -o Acquire::Retries=5 install --no-install-recommends -y \
build-essential \
- gcc \
cmake \
- make \
pkg-config \
- wget \
libcairo2-dev \
libffi-dev \
libpango1.0-dev \
libegl-dev \
&& rm -rf /var/lib/apt/lists/*
-# Setup a minimal TeX Live installation (no ctex: drops ~100 MB of CJK fonts/packages)
-COPY docker/texlive-profile.txt /tmp/
-ENV PATH=/usr/local/texlive/bin/armhf-linux:/usr/local/texlive/bin/aarch64-linux:/usr/local/texlive/bin/x86_64-linux:$PATH
-RUN wget -O /tmp/install-tl-unx.tar.gz http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz \
- && mkdir /tmp/install-tl \
- && tar -xzf /tmp/install-tl-unx.tar.gz -C /tmp/install-tl --strip-components=1 \
- && /tmp/install-tl/install-tl --profile=/tmp/texlive-profile.txt \
- && tlmgr install \
- amsmath babel-english cbfonts-fd cm-super count1to doublestroke dvisvgm everysel \
- fontspec frcursive fundus-calligra gnu-freefont jknapltx latex-bin \
- mathastext microtype multitoc physics prelim2e preview ragged2e relsize rsfs \
- setspace standalone tipa wasy wasysym xcolor xetex xkeyval \
- && rm -rf /tmp/install-tl /tmp/install-tl-unx.tar.gz
-
-# Install manim into an isolated virtualenv
-ENV VIRTUAL_ENV=/opt/venv
-RUN python -m venv $VIRTUAL_ENV
-ENV PATH="$VIRTUAL_ENV/bin:$PATH"
+COPY --from=uv /uv /usr/local/bin/uv
+
+ENV UV_COMPILE_BYTECODE=1 \
+ UV_LINK_MODE=copy \
+ UV_PYTHON=/usr/local/bin/python3 \
+ UV_PYTHON_DOWNLOADS=never \
+ UV_PROJECT_ENVIRONMENT=/opt/venv
-COPY . /opt/manim
WORKDIR /opt/manim
-RUN pip install --no-cache-dir .[jupyterlab]
-# ── Stage 2: runtime ─────────────────────────────────────────────────────────
-FROM python:3.14-slim
+# Third-party dependencies, pinned by uv.lock. This layer is only rebuilt when
+# pyproject.toml or uv.lock change, not on every change to the manim sources.
+RUN --mount=type=cache,target=/root/.cache/uv \
+ --mount=type=bind,source=uv.lock,target=uv.lock \
+ --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+ uv sync --locked --no-dev --no-install-project --extra jupyterlab
+
+# manim itself (non-editable, so the sources are not needed at runtime).
+# pip is added to the virtualenv from the bundled wheel (no download), so that
+# derived images can still `pip install` plugins.
+COPY . /opt/manim
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --locked --no-dev --no-editable --extra jupyterlab \
+ && /opt/venv/bin/python -m ensurepip \
+ && /opt/venv/bin/manim --version
+
+# ── Stage 3: runtime ─────────────────────────────────────────────────────────
+FROM python:${PYTHON_VERSION}-slim
# Runtime libs only:
# - no ffmpeg: PyAV (av package) bundles its own ffmpeg libraries in av.libs/
# - OpenGL: keep EGL for headless rendering and libGL as required by moderngl/glcontext
# - fonts-noto-core instead of fonts-noto (drops CJK noto fonts)
-RUN apt-get update -qq \
- && apt-get install --no-install-recommends -y \
+RUN apt-get -o Acquire::Retries=5 update -qq \
+ && apt-get -o Acquire::Retries=5 install --no-install-recommends -y \
libcairo2 \
libpango-1.0-0 \
libpangocairo-1.0-0 \
@@ -57,32 +118,30 @@ RUN apt-get update -qq \
ghostscript \
fonts-noto-core \
fontconfig \
- && rm -rf /var/lib/apt/lists/*
-
-RUN fc-cache -fv
-
-# Copy TeX Live from builder
-ENV PATH=/usr/local/texlive/bin/armhf-linux:/usr/local/texlive/bin/aarch64-linux:/usr/local/texlive/bin/x86_64-linux:$PATH
-COPY --from=builder /usr/local/texlive /usr/local/texlive
-
-# Copy the pre-built virtualenv from builder
-ENV VIRTUAL_ENV=/opt/venv
-COPY --from=builder /opt/venv /opt/venv
-ENV PATH="$VIRTUAL_ENV/bin:$PATH"
+ && rm -rf /var/lib/apt/lists/* \
+ && fc-cache -f
ARG NB_USER=manimuser
ARG NB_UID=1000
-ENV USER=${NB_USER}
-ENV NB_UID=${NB_UID}
-ENV HOME=/manim
+ENV USER=${NB_USER} \
+ NB_UID=${NB_UID} \
+ HOME=/manim
RUN adduser --disabled-password \
- --gecos "Default user" \
- --uid ${NB_UID} \
- ${NB_USER}
+ --gecos "Default user" \
+ --uid ${NB_UID} \
+ ${NB_USER} \
+ && mkdir -p ${HOME} \
+ && chown -R ${NB_USER}:${NB_USER} ${HOME} \
+ && chmod 777 ${HOME}
+
+COPY --from=texlive /usr/local/texlive /usr/local/texlive
+COPY --from=builder /opt/venv /opt/venv
+
+ENV VIRTUAL_ENV=/opt/venv \
+ PATH=/opt/venv/bin:/usr/local/texlive/bin/linux:$PATH
WORKDIR ${HOME}
-RUN chown -R ${NB_USER}:${NB_USER} ${HOME} && chmod 777 ${HOME}
USER ${NB_USER}
CMD ["/bin/bash"]
diff --git a/docker/readme.md b/docker/readme.md
index 8c5ccc383..b45faf63c 100644
--- a/docker/readme.md
+++ b/docker/readme.md
@@ -14,10 +14,27 @@ docker buildx build --push --platform linux/arm64/v8,linux/amd64 --tag manimcomm
```
from the root directory of the repository.
+To check a built image, render the verification scene (LaTeX, XeLaTeX, Pango, video encoding):
+```
+docker run --rm -v "$PWD/docker:/test:ro" manimcommunity/manim:TAG \
+ manim render -ql --media_dir /tmp/media /test/verify_image.py VerifyImage
+```
+
+# Build notes
+- The image is built via a multi-stage Dockerfile: TeX Live, the Python
+ virtualenv and the runtime image are separate stages, and build dependencies
+ are not carried into the runtime stage.
+- TeX Live is pinned to the frozen final state of a past release (`TL_YEAR`)
+ from the TeX Live historic archive, with fallback mirrors (`TL_REPOSITORIES`).
+ Bump `TL_YEAR` once the next release is frozen. TeX packages are listed in
+ `texlive-packages.txt`.
+- Python dependencies are installed from `uv.lock`.
+- CI builds each platform on a native runner and caches layers, so the TeX
+ Live stage is usually not rebuilt.
+
# Runtime notes
-- The image is built via a multi-stage Dockerfile (build dependencies are not
- carried into the runtime stage).
- The image does not include the `ffmpeg` CLI binary.
- The default TeX installation is minimal and does not include `ctex`.
+ `tlmgr` installs further packages from the same frozen TeX Live release.
- Headless OpenGL rendering relies on EGL/GL runtime libraries available in the
image.
diff --git a/docker/texlive-packages.txt b/docker/texlive-packages.txt
new file mode 100644
index 000000000..b3af1bb9e
--- /dev/null
+++ b/docker/texlive-packages.txt
@@ -0,0 +1,34 @@
+# TeX Live packages installed on top of scheme-minimal (one per line).
+# ctex is left out on purpose: it adds ~100 MB of CJK fonts and packages.
+amsmath
+babel-english
+calligra
+cbfonts-fd
+cm-super
+count1to
+doublestroke
+dvisvgm
+everysel
+fontspec
+frcursive
+fundus-calligra
+gnu-freefont
+jknapltx
+latex-bin
+mathastext
+microtype
+multitoc
+physics
+prelim2e
+preview
+ragged2e
+relsize
+rsfs
+setspace
+standalone
+tipa
+wasy
+wasysym
+xcolor
+xetex
+xkeyval
diff --git a/docker/texlive-profile.txt b/docker/texlive-profile.txt
index 413b46a56..6e8450817 100644
--- a/docker/texlive-profile.txt
+++ b/docker/texlive-profile.txt
@@ -6,5 +6,7 @@ TEXMFLOCAL /usr/local/texlive/texmf-local
TEXMFSYSCONFIG /usr/local/texlive/texmf-config
TEXMFSYSVAR /usr/local/texlive/texmf-var
TEXMFVAR ~/.texlive/texmf-var
-option_doc 0
-option_src 0
+instopt_adjustpath 0
+tlpdbopt_autobackup 0
+tlpdbopt_install_docfiles 0
+tlpdbopt_install_srcfiles 0
diff --git a/docker/verify_image.py b/docker/verify_image.py
new file mode 100644
index 000000000..e4a71e153
--- /dev/null
+++ b/docker/verify_image.py
@@ -0,0 +1,37 @@
+"""Verification scene for the Docker image, rendered by the publish-docker workflow.
+
+Covers LaTeX (default template, and the 3b1b template that loads most of the
+bundled TeX packages), XeLaTeX with fontspec, dvisvgm, Pango text, and video
+encoding via PyAV::
+
+ docker run --rm -v "$PWD/docker:/test:ro" manimcommunity/manim:TAG \
+ manim render -ql --media_dir /tmp/media /test/verify_image.py VerifyImage
+"""
+
+from manim import *
+
+XELATEX = TexTemplate(
+ tex_compiler="xelatex",
+ output_format=".xdv",
+ preamble=r"""
+\usepackage{fontspec}
+\usepackage{amsmath}
+""",
+)
+
+
+class VerifyImage(Scene):
+ def construct(self):
+ tex = MathTex(r"\int_0^1 x^2\,dx = \frac{1}{3}")
+ packages = MathTex(
+ r"\mathds{R} \quad \mathscr{L} \quad \dv{f}{x}",
+ tex_template=TexTemplateLibrary.threeb1b,
+ )
+ # calligra is a METAFONT font, so this also checks on-demand font generation.
+ calligra = Tex(
+ r"{\calligra Calligra}", tex_template=TexTemplateLibrary.threeb1b
+ )
+ xetex = Tex(r"XeLaTeX: \textbf{fontspec}", tex_template=XELATEX)
+ text = Text("Pango text")
+ group = VGroup(tex, packages, calligra, xetex, text).arrange(DOWN)
+ self.play(Write(group), run_time=0.5)