GoogleContainerTools / GoogleContainerTools/distroless

Python distroless: ABI mismatch errors when copying site-packages from builder (request clearer docs & versioned tags)

Open
#1,960 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Starlark
Stars
23.1k
Forks
1.4k
Avg merge
10h 8m
Merged PRs (30d)
26

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.Y` or 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

1. Improve documentation to clearly state:
- Python minor versions must match exactly between builder and distroless runtime
- Copying `/usr/local/lib/pythonX.Y` across versions is unsafe
- Distroless Python is not recommended for ML or native-extension-heavy workloads

2. Consider publishing versioned Python tags (e.g. python3.11-debian12, python3.12-debian12)

3. 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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.