A field-tested migration playbook for moving a Python codebase from mypy to both ty (Astral) and pyrefly (Meta). Covers a 5-phase process: inventorying mypy config, establishing baselines, finding systemic root causes (especially optional C-extension backends like lxml), fixing genuine bugs, and tightening to strict presets. Includes 10 detailed pitfalls such as non-portable `# type: ignore[code]` syntax, pyrefly's snake_case vs kebab-case config inconsistency, Protocol assignability issues, and community stub package bugs. Backed by real case study numbers from the fastkml library migration (237 ty diagnostics reduced to zero, 6 genuine bugs found, $40 Claude API cost).
Table of contents
TL;DRPhase 0 — Inventory the mypy config honestlyPhase 1 — Install both tools and get a baselinePhase 2 — Find the systemic root cause firstPitfalls (the part worth re-reading before your second migration)Phase 3 — Work file by file for what's leftPhase 4 — Tighten to "maximum quality"Phase 5 — VerifyCase study numbers (fastkml)144 Impressions