Distutils compatibility boundary in Python 3.12 deployment builds

Answer the question first

In Python 3.12 the stdlib distutils package is gone. The only stable way to keep a build that imports distutils working is to make the build contract explicit and to pin the exact version of setuptools that supplies the vendored copy. Import-order side-effects are a temporary bridge, not a production guarantee.

Why import-order is fragile

• When setuptools is imported first, its private _distutils_hack inserts a meta-path entry that redirects import distutils to setuptools._distutils.
• In a minimal image that lacks setuptools or that imports distutils before any setuptools import, the shim never runs and the import fails.
• Even if the shim runs, the vendored copy may omit deprecated platform-specific behaviours that legacy code relied on.

Recommended approach

1. Declare a PEP 517 build backend in pyproject.toml:

   [build-system]
   requires = ["setuptools", "wheel"]
   build-backend = "setuptools.build_meta"

   This forces pip to install the declared build dependencies before any build script runs. Pin the exact setuptools version your project has validated.
2. Pin setuptools in the deployment image using the same version declared above:

   RUN pip install "setuptools==<pinned-version>"

   Use the identical version in development and production images so preinstalled site-packages cannot mask a missing dependency.
3. Remove top-level import distutils statements from setup.py or any legacy scripts. Prefer the PEP 517 contract and let setuptools.build_meta drive the build.
4. For legacy setup.py commands that cannot be migrated, import setuptools first in the script, e.g.:

   import setuptools
   import distutils
   # legacy logic

   This guarantees the shim is installed before distutils is used, but treat it as a temporary bridge.
5. Verify the vendored shim by inspecting the path of the imported module in a clean environment:

   python - <<'PY'
   import setuptools, distutils
   print(distutils.__file__)
   PY

   The output should point to site-packages/setuptools/_distutils. A ModuleNotFoundError indicates the shim never ran.
6. Run isolated builds in CI using the same pinned dependencies:

   python -m pip wheel . --no-deps -v

   Compare the output and the generated metadata with a known-good build.

When to migrate fully away from distutils

If a package relies on custom distutils.command classes, compiler hooks, or deprecated platform checks, the vendored copy may not provide the exact behaviour. In that case, migrate the code to setuptools APIs, sysconfig for compiler flags, and importlib.metadata for installed distribution metadata. This is the only path with a stable API contract for future Python releases.

Verification checklist

Check	Command	Expected Result
Shim path	python -c "import distutils; print(distutils.__file__)"	site-packages/setuptools/_distutils/…
Build reproducibility	pip wheel . --no-deps -v	Same wheel hash on dev and prod images
Runtime import	python -c "import distutils"	Success only if runtime code also imports setuptools first
Legacy command	python setup.py build_ext --inplace	Build succeeds with pinned setuptools

Missing diagnostic detail

To refine the recommendation, please share the exact traceback when import distutils fails in the production image, and indicate whether the failure occurs only during the build or also at runtime. Knowing whether the import happens inside setup.py or in a library module changes the safest mitigation strategy.