Python 2 to 3 Migration Checklist

When to Use This Checklist

Use this checklist to migrate a legacy Python 2 codebase to Python 3. Python 2 reached end of life in 2020, so the migration is about security, supportability, and access to modern libraries. The hardest part is not syntax; it is the strict separation of text (str) and bytes, which Python 2 blurred.

How to Use This Checklist

Invest in tests first. The migration is only as safe as your coverage, so raise coverage on critical paths before touching code. Use 2to3 or futurize to handle mechanical changes, then focus human effort on string and bytes handling, removed modules, and integer division. Run the suite under Python 3 with warnings treated as errors to catch deprecations. A six-based compatibility layer lets large codebases run on both versions during a phased transition.

Pin the target minor version, update CI, and roll out behind a canary with the old build kept ready for rollback.

What Good Looks Like

A successful migration runs entirely on a pinned Python 3 version with a green test suite, no deprecation warnings, and all dependencies on Python 3 releases. Text and bytes boundaries are explicit. CI builds and tests on Python 3 only, a canary deployment shows stable error rates, and the Python 2 build remains available until the new version is proven.

Common Pitfalls

The classic failure is migrating with weak tests and discovering encoding bugs in production. Teams treat str/bytes as a syntax issue rather than a semantic one. Hidden dependencies on dropped standard-library modules surface late. Skipping a canary makes a quiet encoding bug a loud outage.

Related Resources

See code coverage best practices and the test pyramid for building the safety net, continuous integration best practices for the pipeline, and canary release practices for rollout.