wbarillon/python-optim repository overview

⁠Python-optim⁠

Python-optim is a Docker image focused on efficiency and performance. It is 30% more performant and slightly heavier than python-slim⁠.

⁠Benchmark

The benchmark compares python-optim with the official python-slim image using wox⁠.

⁠python-slim

CPU (arithmetic tight loop):             5.790275 seconds
List allocation:                         0.191883 seconds
Function calls:                          1.391735 seconds
Dict operations:                         0.215925 seconds
Module imports:                          0.009388 seconds
CPU (Python VM modulo loop):             5.999167 seconds
List allocation:                         0.251999 seconds
Module imports:                          0.010062 seconds
---------------------------------------------------------

⁠python-optim

CPU (arithmetic tight loop):             3.522486 seconds
List allocation:                         0.156373 seconds
Function calls:                          0.977950 seconds
Dict operations:                         0.177474 seconds
Module imports:                          0.008524 seconds
CPU (Python VM modulo loop):             3.972693 seconds
List allocation:                         0.212918 seconds
Module imports:                          0.009252 seconds
---------------------------------------------------------

Average improvement: ~30%

The benchmark environment is available on this repo. Simply run docker compose up.

⁠Motivation

I am a developer working with Python in Docker for years now. Out of curiosity, I wanted to compile a Python interpreter myself. Eventually, I found a combination of compiler and Python build options that work well together. That explains the performance gain.

As for size, I deleted folders that Python developers keep for historical reasons or for backward compatibility. This image is my own, so I am not tied to any constraints but performance and efficiency.

⁠How reliable is this image?

The main way to reduce the size of a Python installation is by not including the tests directory. This directory is not meant for Python users (us) but for Python developer (the ones who actually work on Python). But you can't just delete it and call it a day.

Because if the compiler configuration is wrong, your Python interpreter is corrupt: it works until it doesn't.

To make sure everything went fine during the compilation, it is imperative to enable tests during the compilation.

Sooo how do we actually not include the tests directory meant to test the Python installation and test the Python installation?

Since a compilation is a reproductible process, run the installation with tests activated. If every tests pass, congratulation, you have a properly configured Python compilation. You can know safely disable the tests, which will exclude the tests from the Python installation.

⁠No more virtual environments in Docker

Working on python-optim pushed me to optimize beyond the Python installation itself and into the entire runtime within the container. Naturally, I turned my attention to virtual environments.

After an in-depth investigation, I was able to demonstrate that a virtual environment is not necessary inside a Docker container⁠.

⁠Equivalent to virtual environment "activation" in Docker

FROM python:3.13-slim

ENV PATH="/opt/deps/bin:${PATH}"

RUN echo "/opt/deps/lib/python3.13/site-packages" \
        > /usr/local/lib/python3.13/site-packages/deps.pth \
    && pip install --no-cache-dir --prefix=/opt/deps -r requirements.txt

The next step in the design of python-optim was therefore clear: my image should enforce good practices related to the usage of Python within a Docker container (no venv, no cache).

FROM wbarillon/python-optim:3.13-debian

RUN pip install --prefix=/opt/deps -r requirements.txt

This makes the image even smaller and reduces build time even further.

The process behind the making of this image has existed since November 2025. I kept it private because I wasn't sure whether it would be suitable for every use case.

After several months of using it on different kinds of projects (FastAPI, Django, SQLAlchemy, C++ extensions, Tkinter), I no longer consider this image an experiment. I consider it a reliable image for production use.

To pull the image, I recommend using digests instead of tags.

FROM wbarillon/python-optim:3.13-debian@sha256:<digest>

The digests are available in the repository's container registry.

⁠Other Python versions planned?

I am the only user known user of this Python image at the moment so I only update the version I use.

If you need a specific version or a specific build, let me know by opening an issue⁠.

⁠For Tkinter users

Tkinter support is available in python-optim, but its runtime dependency, is not included in the base image. If your application uses Tkinter, you simply need to install libtk8.6 in your own image.