VVersions.dev

Python 3.8 → 3.12

Python 3.8 is end-of-life. The 3.8 → 3.12 jump is moderate: the main breakage is removed distutils/imp and deprecated collections ABC aliases, in exchange for a faster CPython and newer syntax.

Version upgradeDifficulty: moderateEffort: 0.5–3 days for a typical servicemedium risk

Last verified · Updated May 22, 2026

Python 3.8 reached end of life, so move to a supported 3.x. The 3.8 → 3.12 jump is mostly mechanical: replace removed distutils/imp and deprecated collections ABC aliases, then enjoy a faster CPython and improved f-strings.

Should you upgrade directly?

Yes. There are no source-incompatible jumps that require an intermediate 3.x. Go straight from 3.8 to 3.12, running CI on 3.12 to surface the removed-module and deprecation failures.

Key differences

  • distutils is removed — migrate packaging to setuptools/pyproject.toml.
  • imp is removed — use importlib instead.
  • Deprecated collections ABC aliases (collections.Mapping etc.) are gone; import from collections.abc.
  • asyncio APIs tightened — review get_event_loop and deprecated loop usage.
  • f-string parsing improved and the interpreter is meaningfully faster.
  • Walrus operator and structural pattern matching are available to adopt incrementally.

Files and patterns to inspect

  • setup.py / build scripts importing distutils.
  • Any import imp usage.
  • Imports of collections ABCs from collections instead of collections.abc.
  • asyncio code calling get_event_loop outside a running loop.
  • Pinned dependencies that lack Python 3.12 wheels.

Diagnostic commands

Fail fast on removed-module and deprecation usage
# Recreate the env on 3.12 and surface deprecations as errors$ python3.12 -m venv .venv && . .venv/bin/activate$ pip install -e .$ python -W error::DeprecationWarning -m pytest -q

Pre-migration checklist

  • Green test suite on Python 3.8
  • Dependencies confirmed to publish Python 3.12 wheels
  • CI matrix updated to run on 3.12

Related paths

Official sources

Copy-ready AI prompts

Structured prompts for an AI coding assistant. Inspect first, then execute incrementally, and keep a human in the review loop.

Repo inspectionRepo inspection prompt
You are helping migrate a Python codebase from Python 3.8 to Python 3.12.

Do not edit files yet. First inspect the repository and report:
1. The exact Python version requirement in setup.py / pyproject.toml / tox.ini / CI config, and the interpreter the project runs on.
2. Python 2-only syntax: print statements, integer-division reliance, except Foo, e: syntax, dict.iteritems/iterkeys/itervalues, xrange, and unicode/str/bytes confusion.
3. Removed/deprecated module usage: distutils, imp, and deprecated collections ABC aliases (collections.Mapping etc.).
4. The dependency manifest (requirements.txt vs lock vs pyproject), any C-extension builds, and pinned versions.
5. The test runner, virtualenv/venv setup, and the install/build/test commands.

Return: a migration risk summary, the files most likely to break, a suggested migration order, the commands to run before editing, and any questions that need human confirmation.

Safety: Inspection only. The agent must not modify files in this step.

Works with Claude Code, Cursor, GitHub Copilot

Migration executionMigration execution prompt
Migrate this codebase from Python 3.8 to Python 3.12, one concern at a time.

Work in this order and pause for review after each: (1) create and activate a fresh virtualenv/venv on the target interpreter, (2) run an automated pass with python -m future.utilities futurize (or 2to3) and review the diff, (3) replace removed/deprecated modules (distutils -> setuptools/pyproject, imp -> importlib, collections ABC aliases), (4) fix unicode/bytes boundaries explicitly, (5) reinstall dependencies and resolve pip resolver conflicts.

After each step run pip check and the project's lint and tests, and report results before continuing. Do not refactor unrelated code.

Safety: Apply changes incrementally and keep each step reviewable. Never bundle unrelated refactors.

Works with Claude Code, Cursor, GitHub Copilot

Test plan

Commands

  • python -m venv .venv && . .venv/bin/activate
  • pip install -e .
  • pip check
  • python -m pytest -q

Manual checks

  • Text/bytes: confirm file and network I/O encode/decode explicitly and round-trips.
  • Division: verify code that relied on Python 2 integer division still produces expected results.
  • C extensions: confirm any compiled dependencies build against the target interpreter.

Regression risks

  • Silent behavior change from true division replacing integer division.
  • Bytes/str mix-ups surfacing only at runtime on non-ASCII input.
  • C-extension dependencies without wheels for the target interpreter.

Acceptance criteria

  • pip check reports no broken requirements and pytest passes on the target version.
  • No imports of distutils, imp, or deprecated collections ABC aliases remain.
  • All dependencies resolve to versions supporting the target Python.

Frequently asked questions

Why upgrade off Python 3.8 specifically?

Python 3.8 reached end of life on 2024-10-07 and no longer gets security fixes. Moving to 3.12 restores support and brings substantial interpreter speedups.