From e2b87f205e23686f4b708d0545e5f1db54acb0ed Mon Sep 17 00:00:00 2001 From: kaushalacts Date: Sun, 4 Jan 2026 20:18:25 +0530 Subject: [PATCH 1/2] docs(python3): clarify Python version compatibility and unsafe site-package copying --- python3/README.md | 53 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 50 insertions(+), 3 deletions(-) diff --git a/python3/README.md b/python3/README.md index b692d4b82..be759c9fe 100644 --- a/python3/README.md +++ b/python3/README.md @@ -6,11 +6,58 @@ This image contains a minimal Linux, Python-based runtime. Specifically, the image contains everything in the [base image](../base/README.md), plus: -* Python 3 and its dependencies. -* No shell and no support for ctypes +* Python 3 and its runtime dependencies +* No shell and limited support for native extensions ## Usage -The entrypoint of this image is set to "python", so this image expects users to supply a path to a .py file in the CMD. +This image is intended to run Python applications directly. See the Python [Hello World](../examples/python3/) directory for an example. + +--- + +## ⚠️ Important Usage Notes + +### Python Version Compatibility + +The Python version included in distroless images is provided by the underlying +Debian distribution. Users must ensure that any Python packages copied into the +image were built using the **exact same Python minor version**. + +❌ Unsupported / unsafe pattern + +- Installing dependencies using Python 3.12 in a builder stage +- Copying `/usr/local/lib/python3.12` or site-packages into a distroless image + that uses Python 3.11 + +This may result in runtime errors such as: + +- `SyntaxError: Non-UTF-8 code starting with '\x80'` +- `No module named ` +- Segmentation faults or crashes at startup + +These failures are caused by ABI incompatibilities between Python versions. + +--- + +### Recommended Usage + +Distroless Python images are best suited for: + +- Pure-Python applications +- Minimal dependencies +- Environments where Python version alignment is guaranteed + +For applications with native extensions (e.g. numpy, pandas, torch, ML workloads), +consider using `python:-slim` images instead. + +--- + +### Execution Model + +Distroless images do not include a shell or PATH resolution. Commands must use +absolute paths when invoking the Python interpreter: + +```dockerfile +CMD ["/usr/bin/python3", "-m", "your_module"] From 272a9e5f4a5a9eda79c1b484e376eb9b1e4a0603 Mon Sep 17 00:00:00 2001 From: kaushalacts Date: Sun, 4 Jan 2026 20:45:29 +0530 Subject: [PATCH 2/2] docs(python3): clarify execution model and ENTRYPOINT behavior --- python3/README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/python3/README.md b/python3/README.md index be759c9fe..054e46e44 100644 --- a/python3/README.md +++ b/python3/README.md @@ -56,8 +56,17 @@ consider using `python:-slim` images instead. ### Execution Model -Distroless images do not include a shell or PATH resolution. Commands must use -absolute paths when invoking the Python interpreter: +### Execution Model + +Distroless images do not include a shell. + +The `python3` image provides a default ENTRYPOINT that invokes the Python +interpreter, which allows users to supply a script directly via `CMD` +(as demonstrated in the `examples/python3` directory). + +However, for maximum clarity and to avoid ambiguity—especially in more complex +container configurations—it is often preferable to explicitly invoke the +interpreter using an absolute path: ```dockerfile CMD ["/usr/bin/python3", "-m", "your_module"]