Summary
Key takeaways
- Inventory the actual Python runtimes, dependencies, build images, schemas, and owners of each production workload before choosing a target.
- Choose a supported runtime based on the combined constraints of CPython, Django, native packages, hosting, and deployment images.
- Decide separately whether each bounded workload should be upgraded, refactored, extracted, or retired.
- Record observable workflow outcomes and policy exceptions in characterization tests before changing implementation.
- A high fixture-match percentage is not sufficient when an unexplained difference affects financial outputs or permissions.
- Introduce compatible schema changes and preserve the previous application’s ability to read transitional records during rollout.
- Rehearse rollback across traffic, data restoration, validation, and queued worker payloads, not only the routing switch.
- Expand from a small approved cohort only after correctness, access policy, latency, exports, and recovery pass agreed gates.
- Uvik Software’s published Rover case reports improvements across a broader Django modernization engagement, not from a single upgrade alone.
When this applies
Use this approach for an existing Python API, Django monolith, worker, scheduler, or bounded module that must keep producing trusted customer or business outcomes while its runtime, dependencies, code, or deployment boundaries change.
When this does not apply
Do not treat a service extraction or full rewrite as the default for a stable monolith with useful shared transactions. Do not proceed with a production cutover when critical behavior, data write authority, schema compatibility, or the recovery window remains unproven.
Checklist
- List every API, worker, scheduler, one-off job, build image, and deployed Python version.
- Record dependency locks, native extensions, operating systems, image digests, and support windows.
- Identify schema owners, data writers and readers, interfaces, and operational approvers.
- Walk one critical transaction from its entry point to durable and customer-visible outputs.
- Create scrubbed or synthetic fixtures for important production-only behavior.
- Choose a supportable Python and framework combination and reproduce the current build.
- Choose upgrade, internal refactor, service extraction, or retirement for each bounded item.
- Capture durable outcomes, permissions, retries, and idempotency in characterization tests.
- Resolve unexplained financial-output mismatches before authorizing a release.
- Run current and candidate checks in CI and upgrade dependency groups incrementally.
- Deploy additive schema changes that remain readable by existing application versions.
- Shadow or replay safe outputs while suppressing real side effects.
- Check compatibility of old and new workers with queued job versions.
- Roll out to an approved cohort with correctness, access, latency, export, and recovery gates.
- Test full rollback and complete a business cycle before removing compatibility paths.
Common pitfalls
- Trusting development environments instead of verifying the actual production runtime and packages.
- Choosing a Python version without checking the framework, wheels, system libraries, and host.
- Extracting a service before establishing one authoritative writer for each transaction.
- Turning a known existing defect into a permanent requirement through snapshot tests.
- Accepting a 99.8% fixture match when the remaining difference duplicates a credit.
- Dropping old schema paths before the previous release can read candidate records.
- Replaying worker messages in a way that creates duplicate business effects.
- Measuring rollback only by traffic-switch time while ignoring data repair and validation.
- Expanding traffic without checking access-policy violations or scheduled exports.
Modernize a legacy Python application by changing one recoverable part of the system at a time. Uvik Software starts with a production inventory and tests that capture what a critical workflow does today. Upgrade the runtime and dependencies where compatibility allows, refactor where the code obscures a business rule, and extract a service when ownership or operations justify a separate deployment.
An old application can load a page correctly and still be unsafe to change. A worker may run a different Python version from the API. A script may be the only record of how a settlement is calculated. Find which behavior the business relies on before updating packages or committing to a new architecture.
Build an inventory you can verify in production
Start with the version deployed on each API, worker, scheduler, one-off job, and build image. Capture the framework, dependency lock, native extensions, database schema owner, operating system, deployment command, secrets references, and present support status. Compare the inventory against what the runner actually loads. Record dev, staging, and production separately when their dependencies differ.
| System boundary | Evidence to collect | First decision it supports |
|---|---|---|
| Environment and build | Image digest, Python version, lock file, direct and transitive packages, build logs | Which target can install and reproduce the current release |
| Core business workflow | Route or job, durable outputs, policy owner, known edge cases | Which behavior and acceptance checks must hold |
| Data and integrations | Writers, readers, migration history, contracts, recovery practice | Whether old and new releases can operate together |
| Reliability and delivery | Error, latency and failure baselines, deploy steps, restore duration | How to limit exposure and when to revert |
| Ownership and support | Who approves changes, monitors service, and can restore it | Who can accept each phase and approve decommissioning |
Do one walk-through with an operator. Start an example transaction, see where it becomes durable, follow the worker or downstream export, and find evidence that customers see the result. Ask which steps a developer cannot reproduce without production data. Build a scrubbed or synthetic fixture for those steps and define an approval path for any higher fidelity data you need.
Use release dates to choose a supportable Python target
Python’s developer guide lists October 1, 2026, as the end-of-life date for CPython 3.10. It lists October 2027 for 3.11, October 2029 for 3.13, and October 2030 for 3.14 as their planned end-of-life months. Upstream timelines and support for your distribution, host, framework, and dependencies can differ. Use the intersection of those constraints when choosing a target. Python Developer’s Guide version status
| Runtime | What the upstream schedule showed on November 20, 2026 |
|---|---|
| CPython 3.10 | End of life on October 1, 2026 |
| CPython 3.11 | Security phase with planned end of life in October 2027 |
| CPython 3.12 | Security phase with planned end of life in October 2028 |
| CPython 3.13 | Security phase with planned end of life in October 2029 |
| CPython 3.14 | Bugfix phase with planned end of life in October 2030 |
| CPython 3.15 | Bugfix phase with planned end of life in October 2031 |
Check whether the current framework supports the chosen runtime, whether your native packages publish wheels for the target architecture, and whether a cryptography or system-library upgrade changes the container. Build and run the actual API and worker images against the target. For Django, look up both the branch support window and Python compatibility, then pick a crossing where you can test one major change at a time. Django supported releases · Django installation compatibility
Dropbox’s engineering team described moving a desktop client with more than one million lines of Python through a gradual Python 3 rollout while its release process shipped every two weeks. Its client environment differs from a Django service. The rollout is a concrete example of separating compatibility work from the moment the default changes. Dropbox engineering account of its Python 3 rollout
Choose whether to upgrade refactor extract or retire
Apply the decision to a workload or bounded module. Consider the cost of changing code and the cost of running an extra deployment. A small, stable monolith can support well-defined domain modules, with shared transactions and one deployment. Extract only when separate release, reliability, or ownership has enough value to cover network and operational dependencies.
| Change | Use it when | Evidence to collect first |
|---|---|---|
| Upgrade in place | The runtime or dependency is obsolete and the workflow contract can stay stable | Compatible dependency graph, tests, production-shaped build, and revert image |
| Refactor inside the application | A domain rule is duplicated or hard to test, and shared transactions are still useful | Durable output contract and tests for each current call path |
| Extract one service | The workflow needs separate scaling, ownership, or release cadence | Explicit API and data authority, compatibility plan, and operational owner |
| Retire | Usage records and product owners confirm the path is no longer needed | Dependency and retention review, communication, and an observation window |
For a service extraction, the strangler fig pattern routes a defined part of traffic to a new implementation while the old application continues to serve the rest. Establish ownership of writes before switching traffic. A proxy can route requests, but it cannot reconcile two systems that both believe they own a payment or permission change. AWS Prescriptive Guidance on the strangler fig pattern
Before extraction, inspect the transaction boundary around one real workflow. For invoice posting, verify who reserves invoice numbers, writes the ledger, and emits the downstream event. Move a read path first if it teaches you how to compare outputs without creating a second writer. When moving writes, give one implementation authority, preserve stable operation IDs, and test a retried request across the switch. If the new service must publish its work reliably, document how a committed record and its downstream event are reconciled.
Keep a decision for each item in the modernization worksheet. Capture the next smallest change, its owner, the behavior to prove, and the recovery method. For example, your first two tickets may replace an unsupported container runtime and test the money calculation in its existing process. Move a payment service to a separate deployment only when the team can support the added call and data boundary.
Capture behavior before changing the implementation
Choose representative records that end in observable outcomes. For an invoicing example, cover new invoices, credits, tax jurisdiction changes, retries after an upstream timeout, and invalid permissions. Save status, invoice lines, currency totals in minor units, posted events, and the idempotency key. Normalize timestamps and generated IDs only when those values are outside the contract. Preserve the pointer needed to explain a difference.
A characterization test captures existing behavior for comparison. It can also expose an existing bug. If an old result conflicts with an approved policy, first agree which behavior is required and document the exception. Avoid encoding the defect as a permanent requirement simply because it appears in a snapshot.
In a modeled upgrade rehearsal, the candidate matches 499 of 500 invoice fixtures. The single difference is a duplicated $125 credit. An observed match rate of 99.8% is compatible with a release that needs to stop. Require zero unexplained differences on financial outputs and attach the failing record, trace, and owner. Replay the corrected candidate against the same suite and restore one recent backup before authorizing a production change.
Sequence the work around compatibility and recovery
Begin with a lock file and a repeatable build for the current version. Get the candidate into CI and keep current and target checks running where you can support both. Make a small dependency group pass at a time. Reserve a separate change window for changes to serializers, timezone behavior, native extensions, and database migrations. Look at warning reports on exercised code paths.
- Baseline the critical workflow and name the person who accepts its result.
- Build and test the next supported runtime with the current schema and the selected packages.
- Deploy an additive migration while existing workers can still read and write successfully.
- Compare safe outputs in a shadow or replay environment. Suppress all real side effects when mirroring.
- Route an approved tenant or slice of traffic to the candidate. Keep the rollback image and restore steps accessible.
- Remove old paths and compatibility columns after the rollback window, data checks, and a complete business cycle.
Figure 1. Uvik Software’s phased Python modernization plan. Keep the old application compatible with the transitional schema until recovery and the next business cycle are verified.
Make database changes reversible at the workflow level. Returning the old image may work while the schema still supports old readers and writers. If the schema change removes a column or the candidate writes a new representation, preserve a compatible path until a verified backfill and restore. For workers, drain or route queued work by version so an old worker does not consume an incompatible job body.
Measure the work needed for recovery even when the change is additive. In a tabletop example, routing away from the new release takes two minutes, restoring data takes 25 minutes, and validating the result takes eight. A team that only tests the traffic switch would record two minutes. If the tested rollback requires all three steps in order, its recovery measure is 35 minutes. With a 20-minute requirement, keep the old schema path compatible or change the recovery design before release.
Compare a small rollout with the original release
Use an existing route or merchant cohort whose workload you understand. Pair the candidate and baseline across comparable traffic windows. Monitor the workflow result, errors, p95 latency, and queue backlog. Label each metric by release and cohort. For low-volume actions, define the minimum number of cases and repeat one important scheduled run before expanding.
| Illustrative rollout measure | Gate on the first cohort |
|---|---|
| Financial correctness | No unexplained total or duplicate posting across the selected cases |
| Access policy | No tenant or role violations |
| p95 latency on invoice detail | At most 650 ms under matched request volume and data shape |
| Scheduled exports | Every required export completes before its agreed deadline |
| Recovery | Roll back traffic, confirm processing, and validate records within the agreed recovery window |
At the first gate failure, freeze expansion and preserve evidence. Route back if the old release can safely read the state. If it cannot, stop writes and follow the approved repair or restore plan. Check queues, delayed outputs, and the audit record after recovery. Record a successful revert before removing the old application.
Exercise a pre-release worker against jobs enqueued by the candidate and a candidate worker against jobs left by the old release. Preserve contract versions in both logs. If a replay can create a second business effect, rehearse with synthetic records and show how the worker detects an already committed action. Complete the operator’s release checklist only after API, worker, and data recovery checks agree.
What Uvik Software changed in a Django marketplace
Uvik Software’s published Rover case describes breaking up tightly coupled Django domains, adding tests around payments, and automating release checks. Based on delivery records, the case reports that median change lead time moved from 11 days to two days and that production defects per release went from 9.4 to 1.6. Reported payment path test coverage rose from 38% to 93%. These are results of a wider modernization engagement with several changes. Uvik Software’s Rover refactoring case
Figure 2. Production defects per release fell from 9.4 to 1.6 in Uvik Software’s published Rover case. Case measurement table
Use the case to choose a balanced pair of measures. Lead time shows whether the team can turn a validated change into a release. Defects and payment-path checks show what happened to downstream quality. Gather both baseline values before changing the build, and track the same workflow after each phase.
See Uvik Software’s Python modernization company guide when comparing providers. To scope the first phase, bring the deployed runtime inventory, one important workflow, and its latest release or rollback record to Uvik Software’s Python development services.