How to migrate from mypy to ty

ty is a fast Python type checker, developed by Astral (the creators of uv and Ruff). It runs faster than mypy, especially on large codebases.

Understanding ty

When to consider migrating

• Projects needing faster type checking on large codebases
• Teams already using other Astral tools (Ruff, uv)
• Projects not relying on mypy plugins

When to wait

• Projects requiring Pydantic, Django, or SQLAlchemy mypy plugins
• Projects requiring mature, battle-tested tooling

Installation and basic usage

Installing ty

ty is distributed as a standalone binary. The easiest way to use it is via uvx:

# Run ty directly without installation
uvx ty check .

# Or install globally with uv
uv tool install ty

# Then run
ty check .

For other installation methods, see the ty installation guide.

Basic command equivalents

For all available CLI options, see the ty CLI reference.

Pointing to the Python environment

ty needs to find installed packages to resolve imports:

# Point to a virtualenv or interpreter
ty check . --python .venv

# Or let ty auto-detect from an active virtualenv
ty check .

For more details on how ty discovers and resolves modules, see the module discovery documentation.

Output formats

# Default verbose output
ty check .

# Concise one-line-per-error output
ty check . --output-format concise

# GitHub Actions annotations
ty check . --output-format github

# GitLab Code Quality format
ty check . --output-format gitlab

Automated error suppression with –add-ignore

When migrating from mypy to ty, you may encounter many new type errors that you want to address gradually. The --add-ignore flag automates the process of suppressing these errors by adding ty: ignore[codes] comments throughout your codebase.

# Add ignore comments for all current errors
ty check . --add-ignore

# Verify no new errors remain
ty check .

ty groups multiple error codes per comment, extends existing ty: ignore comments where they already exist, and validates that the file still parses. Treat the suppressed errors as a todo list, not a fix.

Migrating configuration

Configuration file locations

mypy supports:

• mypy.ini
• pyproject.toml → [tool.mypy]
• setup.cfg → [mypy]
• .mypy.ini

ty supports:

• ty.toml (takes precedence)
• pyproject.toml → [tool.ty]
• User-level: ~/.config/ty/ty.toml

For complete configuration details, see the ty configuration guide.

Basic option mapping

[tool.ruff.lint]
select = [
  "ANN001", # flake8-annotations
  "ANN201",
]

Example configuration migration

mypy (pyproject.toml):

[tool.mypy]
python_version = "3.11"
ignore_missing_imports = true
exclude = ["tests/", "docs/"]
check_untyped_defs = true
warn_redundant_casts = true

ty (pyproject.toml):

[tool.ty.environment]
python-version = "3.11"

[tool.ty.terminal]
error-on-warning = true

[tool.ty.src]
exclude = ["**/tests/**", "**/docs/**"]

[tool.ty.rules]
unresolved-import = "ignore"
# Note: check_untyped_defs is ty's default behavior
# warn_redundant_casts equivalent: warnings are on by default

Per-module overrides

mypy:

[[tool.mypy.overrides]]
module = ["mypackage.legacy", "mypackage.legacy.*"]
ignore_errors = true
disallow_untyped_defs = false

ty:

[[tool.ty.overrides]]
include = ["mypackage/legacy/**"]
rules = { unresolved-attribute = "ignore", invalid-assignment = "ignore" }

Handling mypy plugins

ty has no plugin system and no plan to add one. Some popular libraries may get native ty support over time.

If your project uses mypy plugins, this is a significant migration consideration.

Workaround for Pydantic projects:

[tool.ty.rules]
invalid-argument-type = "ignore"  # Pydantic model constructors
invalid-key = "ignore"            # TypedDict/Pydantic interop
invalid-parameter-default = "ignore"  # Field defaults

CI integration

Current mypy CI patterns

Common patterns found in production projects:

Pattern 1: Dedicated mypy workflow

name: Mypy
on: [push, pull_request]
jobs:
  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install -e .[dev]
      - run: mypy src/

Pattern 2: Matrix across Python versions

strategy:
  matrix:
    python-version: ['3.10', '3.11', '3.12', '3.13']
steps:
  - run: mypy google/genai/

Migrating to ty

Replace mypy with ty:

name: Type Check
on: [push, pull_request]
jobs:
  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install -e .[dev]
      - run: pip install uv
      # Use uvx to run ty without installation
      - run: uvx ty check src/ --python .venv
      # Or, if ty is a dev dependency:
      # - run: uv run ty check src/

With GitHub Actions annotations:

- run: uvx ty check src/ --output-format github

Running both type checkers during transition

During migration, run both checkers:

jobs:
  mypy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install -e .[dev] mypy
      - run: mypy src/

  ty:
    runs-on: ubuntu-latest
    continue-on-error: true  # Don't fail build yet
    steps:
      - uses: actions/checkout@v4
      - run: pip install -e .[dev]
      - run: uvx ty check src/ --python .venv || true

Handling dual-ignore comments

When running both checkers, you will encounter cases where mypy requires a # type: ignore comment that ty considers unnecessary. ty flags these with unused-ignore-comment, producing lines like:

result = func()  # type: ignore[assignment]  # ty: ignore[unused-ignore-comment]

The first comment silences mypy. The second silences ty’s complaint about the first. This is an unavoidable cost of the dual-checker approach and a strong signal that the codebase is ready to drop mypy.

Common migration issues

Issue 1: ty checks untyped code by default

Symptom: Massive increase in errors for unannotated codebases.

Why it happens: mypy skips function bodies without type annotations by default. ty checks everything.

Example (NetworkX: 580 files, ~192k LOC):

• mypy: 0 errors
• ty: ~1,200 errors

Solution for unannotated code:

[tool.ty.rules]
# Ignore errors that arise from missing type info
unresolved-attribute = "ignore"
possibly-missing-attribute = "ignore"
invalid-assignment = "ignore"

Or exclude unannotated modules (see file exclusions):

[tool.ty.src]
exclude = ["legacy/**", "untyped/**"]

Issue 2: Missing import resolution

Symptom: unresolved-import errors for installed packages.

Why it happens: ty needs to know where the Python environment is.

Solution:

[tool.ty.environment]
python = ".venv"

Or via CLI:

uvx ty check . --python .venv

For optional dependencies:

[tool.ty.rules]
unresolved-import = "ignore"

Issue 3: Different type narrowing behavior

Symptom: Errors like “Attribute may be missing” after type guards.

Example (from IPython):

if _is_sizable(completions):
    return len(completions) != 0  # ty: Expected Sized, found Iterator

Why it happens: ty and mypy have different type narrowing algorithms.

Solution: Usually requires code changes or ignoring specific rules:

[tool.ty.rules]
possibly-missing-attribute = "ignore"

Or inline comments:

return len(completions) != 0  # ty: ignore[invalid-argument-type]

Issue 4: Pydantic model errors

Symptom: Many errors related to Pydantic BaseModel, Field, TypedDict.

Example (from python-genai):

options: RequestOptions = {}  # ty error: dict not assignable to RequestOptions

Why it happens: No Pydantic plugin support in ty.

Solution: Extensive rule ignoring:

[tool.ty.rules]
invalid-argument-type = "ignore"
invalid-key = "ignore"
invalid-parameter-default = "ignore"

Issue 5: No equivalent for ignore_errors = true

Symptom: Modules with ignore_errors = true in mypy still report errors.

Solution: Use overrides to ignore all rules for those files:

[[tool.ty.overrides]]
include = ["src/legacy/**"]
rules = {
  unresolved-attribute = "ignore",
  invalid-assignment = "ignore",
  invalid-argument-type = "ignore"
  # ... add more as needed
}

Or exclude them entirely:

[tool.ty.src]
exclude = ["src/legacy/**"]

Error code mapping reference

This table maps common mypy error codes to their ty rule equivalents.

Related resources

• ty reference
• mypy reference
• How to try the ty type checker
• uv reference
• Ruff reference