Using mypy with an existing codebase

Strategies for adopting mypy in large, existing Python codebases

This guide explains how to get started using mypy with an existing, significant codebase that has little or no type annotations.

Start small

If your codebase is large, pick a subset (5,000 to 50,000 lines) and get mypy to run successfully only on this subset first, before adding annotations.

1. Choose a subset

   Select a manageable portion of your codebase to start with. This should be doable in a day or two.

2. Get mypy passing

   Fix mypy errors by:

   • Inserting annotations requested by mypy
   • Adding # type: ignore comments to silence errors you don’t want to fix now
3. Expand gradually

   Once you have mypy passing on a subset, gradually expand to more code.

The sooner you get some form of mypy passing on your codebase, the sooner you benefit from type checking.

Run mypy consistently

Make sure all developers run mypy the same way:

Configuration file

Check a mypy configuration file into your codebase:

# mypy.ini
[mypy]
python_version = 3.10
warn_return_any = True
warn_unused_configs = True

[mypy-tests.*]
disallow_untyped_defs = False

Standardized invocation

Create a script or add to existing tools:

Script

#!/bin/bash
# scripts/run_mypy.sh
python3 -m mypy my_project

Pin mypy version

Ensure everyone runs the same mypy version:

# requirements-dev.txt
mypy==1.8.0
types-requests==2.31.0

Different mypy versions may report different errors. Pin the version to prevent surprises.

Continuous Integration

Add mypy to your CI pipeline as soon as possible:

# .github/workflows/type-check.yml
name: Type checking
on: [push, pull_request]

jobs:
  mypy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install dependencies
        run: |
          python3 -m pip install mypy==1.8
          python3 -m pip install -r requirements.txt
      - name: Run mypy
        run: mypy my_project

This prevents new type errors from being introduced.

Ignoring errors from certain modules

By default, mypy follows all imports and checks everything. This can result in many errors you don’t want to deal with yet.

Ignore specific modules

Use the ignore_errors option:

[mypy-package_to_fix_later.*]
ignore_errors = True

Invert the pattern

For very large codebases, you can ignore everything by default:

[mypy]
ignore_errors = True

[mypy-package.module_a]
ignore_errors = False

[mypy-package.module_b]
ignore_errors = False

Per-module configuration

Many options can be configured per-module:

[mypy-tests.*]
disallow_untyped_defs = False

[mypy-legacy.*]
check_untyped_defs = False
ignore_errors = True

[mypy-newcode.*]
strict = True

Fixing import errors

A common error when starting with mypy:

core/config.py:7: error: Cannot find implementation or library stub for module named 'frobnicate'
core/model.py:9: error: Cannot find implementation or library stub for module named 'acme'

Solutions

Install stub packages

Many popular packages have stub packages:

pip install types-requests types-redis types-PyYAML

Search for stubs:

mypy --install-types

Ignore missing imports

For packages without stubs:

[mypy-frobnicate.*]
ignore_missing_imports = True

Create your own stubs

Create a .pyi file for the module:

# stubs/frobnicate.pyi
def process(data: str) -> dict: ...

Then set MYPYPATH:

export MYPYPATH=./stubs

Incremental adoption strategies

Strategy 1: Bottom-up

Start with modules that have few dependencies:

1. Find leaf modules

   Identify modules with minimal imports

2. Add type hints

   Fully annotate these modules

3. Move upward

   Gradually work toward modules that depend on the annotated ones

Strategy 2: Top-down

Start with high-level modules:

1. Choose entry points

   Pick main modules or public APIs

2. Add basic annotations

   Add type hints to function signatures

3. Ignore dependencies

   Use ignore_missing_imports for unannotated dependencies initially

Strategy 3: Feature-based

Annotate by feature or component:

• New features: Require full type hints
• Bug fixes: Add type hints to modified code
• Refactoring: Use as opportunity to add types

Dealing with type errors

Quick fixes

Type: ignore

Suppress individual errors:

result = legacy_function()  # type: ignore[no-untyped-call]

Any type

Use Any for complex cases:

from typing import Any

def process(data: Any) -> dict:
    # Will refine later
    return transform(data)

Cast

Use cast when you know better than mypy:

from typing import cast

value = cast(str, get_value())

Long-term fixes

1. Add proper type annotations
2. Refactor code to be more type-friendly
3. Use protocols for duck-typed code
4. Create stub files for third-party libraries

Measuring progress

Track your progress over time:

# Count type: ignore comments
grep -r "type: ignore" . | wc -l

# Use mypy's stats
mypy --txt-report report my_project

Tips for success

Be patient

Adopting mypy in a large codebase takes time. Celebrate incremental progress.

Educate the team

Make sure everyone understands the benefits and how to write typed code.

Set policies

Decide on rules: e.g., “all new code must have type hints”

Review together

Use code review to improve type annotations and share knowledge.

The goal isn’t 100% coverage immediately. Even partial type checking provides significant value.