Python distroless: ABI mismatch errors when copying site-packages from builder (request clearer docs & versioned tags) #1960
Description
Description
When using distroless Python images in a multi-stage Docker build, copying Python site-packages from a builder image frequently results in runtime failures such as:
SyntaxError: Non-UTF-8 code starting with '\x80' in file /usr/bin/python3
or:
No module named
This typically occurs when:
- Dependencies are installed using Python X.Y (e.g., 3.12) in a builder image
- The distroless runtime image uses a different Python minor version (e.g., Debian 12 Python 3.11)
/usr/local/lib/pythonX.Yor site-packages are copied into the distroless image
The failure mode is non-obvious and appears as Python corruption, but is actually an ABI/version mismatch.
Root Cause
Distroless Python images ship a Python interpreter provided by the Debian base distribution.
They do not support arbitrary Python minor versions or mixing site-packages built against a different interpreter.
This limitation is not clearly documented and can easily surprise users building modern Python applications.
Proposal
-
Improve documentation to clearly state:
- Python minor versions must match exactly between builder and distroless runtime
- Copying
/usr/local/lib/pythonX.Yacross versions is unsafe - Distroless Python is not recommended for ML or native-extension-heavy workloads
-
Consider publishing versioned Python tags (e.g. python3.11-debian12, python3.12-debian12)
-
Provide an official example showing safe usage patterns and common pitfalls
Why this matters
Many modern Python workloads (FastAPI, ML inference, embeddings, pandas, torch, chromadb) rely on native extensions.
Without clear guidance, users often encounter runtime crashes that are difficult to debug.
Better documentation would significantly improve developer experience.
Environment
- distroless image: python3-debian12
- builder image: python:3.12-slim
- workload: FastAPI + uvicorn + ML dependencies