Skip to content

Docker and servers

This page changed after phonometry 4.0.0, the latest release on PyPI, so it may describe code that release does not have yet. What is new since then is listed under Unreleased in the changelog.

phonometry needs nothing from the operating system beyond Python on a python:*-slim image for x86-64 or ARM64 (linux/amd64, linux/arm64): every extra installs from wheels there, libsndfile inside the soundfile wheel included. The one system package worth adding is ffmpeg, and only for videos. The same tag publishes six more architectures, and Docker pulls the one of the host: 32-bit ARM (linux/arm/v5, linux/arm/v7), 32-bit x86 (linux/386), linux/ppc64le, linux/riscv64 and linux/s390x. numba no longer supports 32-bit Linux, where its last wheels, of 0.56.4, are for Python 3.10 at most, so neither [perf] nor [full], which holds it, is supported on the three 32-bit ones, where python -m pip install "phonometry[plot,report,audio]" installs the other three extras. torch publishes no wheel for any of the six and no source to build, so [torch] does not install on them from PyPI. PyPI has no Python 3.13 wheel for any of the six of NumPy, SciPy, matplotlib or Pillow, nor of numba and the llvmlite it needs on linux/ppc64le, linux/riscv64 and linux/s390x, which numba supports on a best-effort basis only, nor for some of them of contourpy, kiwisolver, cffi or lxml, so pip builds those from source there, NumPy and SciPy even for a plain install. That takes what the slim image leaves out: a C and a C++ compiler and the development files of the libraries each one links, a Fortran compiler with BLAS and LAPACK for SciPy, and for llvmlite LLVM 22 with cmake and make on PATH. python-soundfile installs its pure-Python wheel there, which loads the system’s libsndfile: apt-get install libsndfile1. On linux/arm/v5, whose soft-float ABI no manylinux wheel targets, the builds of NumPy, SciPy and matplotlib also ask for ninja and patchelf, and pip would build those from source too, which runs make and autoreconf, unless apt-get install ninja-build patchelf has put the image’s own on PATH. An Alpine image, built on musl, needs more, since python-soundfile has no wheel there that carries libsndfile and numba none at all; Getting Started says what each extra takes there.

Checked on 17 November 2026 with phonometry 4.0.0 from PyPI, with Docker 29.9.3 and the python:3.13-slim image of digest sha256:09a17cad02668ae61ece136b4fd36ac3849e14f670ebedb637ea3e15580525bc on Python 3.13.18: the image and the job below, as root, as another user id, as nobody and on a read-only root.

FROM python:3.13-slim
RUN python -m venv /opt/venv \
&& /opt/venv/bin/python -m pip install --no-cache-dir --upgrade pip \
&& /opt/venv/bin/python -m pip install --no-cache-dir "phonometry[full]"
ENV PATH=/opt/venv/bin:$PATH MPLCONFIGDIR=/tmp/matplotlib
COPY analyse.py /app/analyse.py
WORKDIR /tmp
CMD ["python", "/app/analyse.py"]

The virtual environment keeps pip’s warning about running as root out of the build log. analyse.py stands for your own job; this one writes a band spectrum, its figure and a fiche:

"""A batch job: a one-third-octave analysis, its figure and a fiche."""
from pathlib import Path
import numpy as np
from phonometry import building, filters
out = Path("out")
out.mkdir(exist_ok=True)
fs = 48000
t = np.arange(2 * fs) / fs
x = 0.1 * np.sin(2 * np.pi * 1000 * t)
bands = filters.octave_filter(x, fs, fraction=3)
bands.plot().figure.savefig(out / "bands.png")
impulse = filters.time_weighting(x, fs, mode="impulse")
rating = building.weighted_rating(
[30, 34, 38, 41, 45, 49, 50, 53, 54, 55, 56, 57, 58, 58, 58, 58]
)
rating.report(out / "rating.pdf")
print(f"{len(bands.frequencies)} bands, impulse maximum {float(np.max(impulse)):.4f}")
print("wrote", sorted(p.name for p in out.iterdir()))
Terminal window
docker build -t acoustics .
mkdir -p out
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD/out:/tmp/out" acoustics
33 bands, impulse maximum 0.0092
wrote ['bands.png', 'rating.pdf']

The job writes into out under its working directory, /tmp/out in the container, and --rm deletes the container with its files when the job ends. The -v mount gives that folder to the host as out in the directory you run from, where the figure and the fiche stay. With a Docker daemon that runs as root, --user runs the job as you, so the files are yours and not root’s. Make the folder first: one that such a daemon makes for the mount belongs to root, and the job, running as you, cannot write in it.

Rootless Docker and rootless Podman already run the container’s root as you, and map every other user id of the container, your own included, to a subordinate id of the host that cannot write in your out: there --user stops the job with a PermissionError. Leave it out, or pass --userns=keep-id under Podman, and the files are yours. The folder made first serves both: rootless Docker would make a missing one as you, and Podman refuses to mount one that does not exist.

matplotlib picks its Agg backend by itself in a container with no display, so nothing has to set MPLBACKEND.

The image runs the same job as root, as an arbitrary user id (docker run --user 12345:12345), as nobody, and on a read-only root file system with a writable /tmp (docker run --read-only --tmpfs /tmp). A folder mounted for the results has to be writable by the user the job runs as, as out is for you above. Two caches and one directory decide how quietly it does so:

  • MPLCONFIGDIR. matplotlib keeps its configuration and cache under the user’s home. For a user with no writable home it prints “Matplotlib created a temporary cache directory at …” each time it starts; the ENV line above points it at /tmp instead, and it says nothing.
  • numba’s cache. numba keeps the compiled impulse kernel beside the package or under the home directory. Where it can write to neither, it compiles the kernel once in each process instead and says nothing. With NUMBA_CACHE_DIR=/tmp/numba it writes the kernel there, for the processes that follow in the same container.
  • A read-only root. The job needs somewhere to write: here its working directory, /tmp, which --tmpfs /tmp keeps writable, and the out folder mounted inside it from the host. With no writable mount at all, the job stops at its own out.mkdir.

io.write_video and the FDTD animation writers run ffmpeg. Install it from the image’s own packages before the virtual environment:

FROM python:3.13-slim
RUN apt-get update \
&& apt-get install -y --no-install-recommends ffmpeg \
&& rm -rf /var/lib/apt/lists/*
RUN python -m venv /opt/venv \
&& /opt/venv/bin/python -m pip install --no-cache-dir --upgrade pip \
&& /opt/venv/bin/python -m pip install --no-cache-dir "phonometry[full]"
ENV PATH=/opt/venv/bin:$PATH MPLCONFIGDIR=/tmp/matplotlib

WebM and MP4 then encode on the CPU, as nobody and on a read-only root with a writable /tmp alike. Writing videos covers the encoders and a node that has a GPU.

A server that handles requests in a thread pool may import the domains it needs from those threads, several at once. Sending a simulation to a remote node covers an FDTD run the server should not step itself.