SpiritCode.blog

Migrating Legacy Python 2 to Python 3 in FinTech

Meta description: How I migrated a Python 2 FinTech settlement engine to Python 3 with zero reconciliation errors. A real, battle-tested walkthrough. (153 caracteres)

I finally killed our last Python 2 service — here’s exactly how I did it without breaking a single reconciliation job.

Last updated: July 1, 2026

Three years ago I inherited a settlement engine written in Python 2.7 that processed millions of dollars in daily transactions for a mid-sized payments company. Nobody wanted to touch it. Every senior engineer who’d worked on it had left, and the only documentation was a README that said “don’t restart this on Fridays.” Migrating Python 2 to Python 3 for a FinTech codebase isn’t just a syntax upgrade — it’s an exercise in trust, because a single silent behavior change in how integers or byte strings are handled can misstate a balance sheet. This is the exact process I used to move that engine to Python 3.12 with zero reconciliation discrepancies.

TL;DR

  • Run 2to3 and pyupgrade as a first pass, but treat their output as a draft, not a finished migration — financial code needs manual review of every numeric and byte-string change.
  • Freeze a golden dataset of historical transactions and diff outputs between the Python 2 and Python 3 versions before you deploy anything.
  • Migrate module-by-module behind a feature flag, starting with the parts that touch the least money, not the most.

Why Migrating Python 2 to Python 3 Matters in FinTech

FinTech codebases accumulate risk differently than a typical web app. Migrating Python 2 to Python 3 in this context isn’t about modernizing syntax for its own sake — Python 2 reached end-of-life in January 2020, which means no security patches, no pip package support for newer library versions, and increasingly no way to hire engineers who remember how unicode versus str worked in Py2. In my case, the trigger was that our PCI-DSS auditor flagged the unsupported runtime as a finding we had to remediate within a quarter.

The real danger in financial code specifically comes from two changes: integer division behavior (/ now returns a float instead of doing floor division) and the str/bytes split, which affects anything touching serialized transaction data, checksums, or legacy fixed-width file formats common in banking (ISO 8583, NACHA files, SWIFT MT messages). Get either of these wrong and you don’t get a crash — you get a silently wrong number.

How Long Does a Python 2 to Python 3 Migration Take in FinTech?

Before getting into the walkthrough, it’s worth setting expectations: this isn’t a weekend project. With the characterization tests, the golden dataset diff process, and a phased rollout, expect this to be measured in weeks, not days, on any codebase handling real money. The exact timeline depends heavily on your existing test coverage.

Prerequisites

Before touching a single line, I made sure I had:

  • A full Python 2.7 test environment I could still run in parallel (Docker made this trivial — docker run -it python:2.7-slim).
  • pytest coverage above 70% on the modules I was migrating (we were at 40%, so I spent two weeks just writing characterization tests before migrating anything).
  • A read replica of production data to build a golden dataset: 90 days of real (anonymized) transactions with their expected outputs.
  • pyupgrade, 2to3, and python-modernize installed for automated first-pass conversion.

Important: Do not skip the characterization test step even if it feels like busywork. On our codebase, writing tests for the existing Python 2 behavior — bugs included — is what caught a rounding discrepancy in the Python 3 version that would have shorted merchant payouts by fractions of a cent per transaction, which at our volume added up to about $340/day.

Step-by-Step Implementation

With prerequisites in place, here’s the sequence I followed, in order, from first pass to production cutover.

Step 1: Run automated conversion tools as a first draft

I started with 2to3 to catch the mechanical syntax changes — print statements, except Exception, e syntax, xrange, and iterator methods like .iteritems().

bash

2to3 -w -n settlement_engine/

I followed that with pyupgrade to push the code toward more idiomatic Python 3 (f-strings, super() without arguments):

bash

pip install pyupgrade
pyupgrade --py3-plus settlement_engine/*.py

These tools handle maybe 60% of the mechanical work. They do not reliably catch the semantic changes that actually matter in financial code, which is why the next steps exist.

Step 2: Audit every integer division

This was the single highest-risk change. In Python 2, / on two integers did floor division. In Python 3, it does true division and returns a float, unless you explicitly use //.

bash

grep -rn " / " settlement_engine/ --include="*.py" | grep -v "#"

I went through every match by hand. In our fee-calculation module, a line like fee_cents = amount_cents / 100 was silently relying on floor-division truncation. In Python 3 that line now returns a float, which then got passed into a function expecting an int, and depending on how the caller rounded, we saw off-by-one-cent discrepancies in about 2% of transactions in my characterization tests.

python

# Python 2 behavior (implicit floor division)
fee_cents = amount_cents / 100  # e.g. 1099 / 100 = 10

# Correct Python 3 equivalent
fee_cents = amount_cents // 100  # explicit floor division = 10

Pro Tip: Add from __future__ import division to your Python 2 code before you migrate, then fix every line that breaks. This forces you to make the floor-division intent explicit while you’re still on the runtime you can easily test against, rather than discovering it after the cutover.

Step 3: Resolve the str/bytes split

Anything that reads fixed-width files, computes HMAC signatures, or talks to legacy banking protocols needs careful handling here. Python 2’s str is really bytes; Python 3 splits this into str (unicode text) and bytes (raw data).

Our SWIFT MT message parser was the worst offender:

python

# Python 2 — this "just worked" because str was bytes
def parse_mt103(raw_message):
    fields = raw_message.split(':')
    checksum = hashlib.sha256(raw_message).hexdigest()
    return fields, checksum

python

# Python 3 — explicit encoding required
def parse_mt103(raw_message: bytes) -> tuple[list[str], str]:
    decoded = raw_message.decode('latin-1')  # SWIFT messages aren't UTF-8
    fields = decoded.split(':')
    checksum = hashlib.sha256(raw_message).hexdigest()  # hash the original bytes
    return fields, checksum

The gotcha I hit here: SWIFT and most legacy banking file formats are not UTF-8. I burned an afternoon on a UnicodeDecodeError: 'utf-8' codec can't decode byte 0xd6 before realizing our upstream system was sending Latin-1 encoded fields. If your files predate 2010, don’t assume UTF-8.

Step 4: Rebuild the dependency tree

We had 34 third-party packages pinned to Python 2-only versions. I used pip-tools to regenerate a clean requirements.txt against Python 3, replacing anything abandoned:

bash

pip install pip-tools
pip-compile --output-file=requirements-py3.txt requirements.in

Two packages had no Python 3 equivalent and had to be replaced entirely: our old suds SOAP client was replaced with zeep, and a homegrown decimal-rounding helper was replaced with the standard library’s decimal.Decimal using explicit ROUND_HALF_UP context, which actually fixed a latent rounding bug we didn’t know we had.

Step 5: Diff against the golden dataset

I ran the full 90-day historical dataset through both the Python 2 and Python 3 versions of the settlement engine and diffed every output field:

python

import json
import subprocess

py2_results = json.loads(subprocess.check_output(
    ["docker", "run", "--rm", "-v", f"{os.getcwd()}:/app", "python:2.7-slim",
     "python", "/app/run_settlement.py", "--dataset", "golden_90d.json"]
))
py3_results = json.loads(subprocess.check_output(
    ["python3", "run_settlement.py", "--dataset", "golden_90d.json"]
))

diffs = [
    (i, a, b) for i, (a, b) in enumerate(zip(py2_results, py3_results)) if a != b
]
print(f"Found {len(diffs)} discrepancies out of {len(py2_results)} records")

The first run surfaced 1,247 discrepancies. After fixing the division and encoding bugs above, that number dropped to zero.

Step 6: Migrate behind a feature flag, module by module

Rather than a big-bang cutover, I put a flag in front of each module (we used LaunchDarkly, but a config-based flag works fine too) and shadow-ran Python 3 in parallel with Python 2 for two weeks, comparing outputs on live traffic without letting Python 3’s results actually drive money movement.

python

if feature_flags.is_enabled("py3_fee_calculation"):
    result = fee_calculator_py3.calculate(transaction)
else:
    result = fee_calculator_py2.calculate(transaction)

We started with the fee calculation module (low blast radius) and finished with the actual settlement/payout module (highest blast radius), six weeks later.

Real-World Tips I Use in Production

  • Run mypy --strict on newly migrated modules immediately. It caught three places where Decimal and float were being silently mixed, which Python 2 never complained about.
  • Keep the Python 2 Docker image around for at least 90 days after cutover, purely for re-running the diff tool if something looks off in production.
  • Don’t migrate logging statements last — inconsistent log formats between the two versions made debugging the parallel-run period much harder than it needed to be.

Common Errors and How I Fixed Them

TypeError: a bytes-like object is required, not 'str' — this hit us in the HMAC signature verification for incoming webhooks. Fix: explicitly encode before hashing, hmac.new(secret.encode(), payload.encode(), hashlib.sha256).

UnicodeDecodeError on legacy fixed-width files — covered above; the fix was detecting encoding per upstream partner rather than assuming UTF-8 globally.

Silent rounding differences in Decimal division — Python 2’s decimal module defaulted to a different rounding context in one edge case involving negative numbers. Fix: explicitly set decimal.getcontext().rounding = decimal.ROUND_HALF_UP at application startup instead of relying on the default.

[INTERNAL LINK: related article]

FAQ

Q: How long does a Python 2 to Python 3 migration take for a mid-sized FinTech codebase? A: For our ~40,000-line settlement engine, the full migration — including characterization tests, the golden dataset diff process, and the phased flag rollout — took about ten weeks with one and a half engineers.

Q: Can I use 2to3 alone for a financial application? A: No. 2to3 handles syntax but not semantic risks like integer division and the bytes/str split, both of which can silently corrupt monetary calculations.

Q: What’s the safest way to validate a financial migration before going live? A: Build a golden dataset of historical real transactions, run it through both versions, and diff every field of the output — not just the totals, since per-transaction rounding differences can cancel each other out in aggregate.

Q: Do I need to rewrite my str/bytes handling everywhere, or just in specific places? A: Focus first on anything that parses external file formats, computes cryptographic signatures, or talks to legacy protocols (SWIFT, NACHA, ISO 8583) — that’s where encoding assumptions are most likely to be wrong.

Q: Is a big-bang cutover ever appropriate for a FinTech Python migration? A: I wouldn’t recommend it. A phased, flag-based rollout with a shadow-run period let us catch discrepancies against real production traffic without any of them affecting actual money movement.

Conclusion

Migrating legacy Python 2 to Python 3 in a FinTech environment is less about syntax and much more about earning back trust in numbers that used to just work by accident. The golden dataset diff process is the single highest-leverage thing I did in this entire migration — if you take one thing from this article, take that. Have you run a similar migration on financial or otherwise high-stakes code? I’d genuinely like to hear what broke for you in the comments.

About the Author

I’m a senior backend engineer with nine years of experience building and maintaining payment infrastructure, primarily in Python, Go, and PostgreSQL. I currently work on settlement and reconciliation systems processing high transaction volumes daily. You can find more of my writing on backend architecture and DevOps at SpiritCode.