/migration-patterns:mypy-to-ty

Migrate from mypy to ty — Astral's new fast Python type checker. Replaces the mirrors-mypy pre-commit hook with a local repo: local hook using uvx ty check, migrates config from [tool.mypy] to [tool.ty], and removes mypy.ini.

When to Use This Skill

Use this skill when...	Keep mypy when...
.pre-commit-config.yaml contains mirrors-mypy	ty does not yet support a specific mypy plugin you rely on
[tool.mypy] section exists in pyproject.toml	CI pipeline depends on mypy-specific exit codes or plugins
You want faster type checking (ty is written in Rust)	Project uses mypy daemon (dmypy) for incremental checks
Repo uses uv and the astral stack already	Team prefers mypy's error message format

Context

• Pre-commit config: !find . -maxdepth 1 -name '.pre-commit-config.yaml'
• pyproject.toml: !find . -maxdepth 1 -name 'pyproject.toml'
• mypy.ini: !find . -maxdepth 1 -name 'mypy.ini'
• uv available: !find . -maxdepth 1 -name 'uv.lock'

Parameters

Parameter	Description
--check-only	Report what would change without modifying files
--fix	Apply migration automatically

Execution

Execute this mypy-to-ty migration:

Step 1: Audit current mypy configuration

1. Read .pre-commit-config.yaml and locate any mirrors-mypy or mypy entries.
2. Read pyproject.toml and extract the [tool.mypy] section.
3. Check for mypy.ini.
4. Report findings:

   mypy → ty migration audit
   ==========================
   pre-commit hook:   mirrors-mypy found at rev <rev>
   pyproject.toml:    [tool.mypy] section found (N lines)
   mypy.ini:          FOUND / NOT FOUND
   uv.lock:           EXISTS (uv available) / MISSING
   

   If --check-only, stop here.

Step 2: Update .pre-commit-config.yaml

Remove the mirrors-mypy repo block. Add a repo: local hook for ty:

- repo: local
  hooks:
    - id: ty
      name: ty type check
      entry: uvx ty check
      language: system
      types: [python]
      pass_filenames: false

Note: astral-sh/ty-pre-commit does not yet exist as a hosted pre-commit repo. The repo: local pattern with uvx ty check is the correct approach until an official mirror is published.

If an entry: mypy hook in a non-mirrors-mypy repo exists, replace it similarly.

Step 3: Migrate [tool.mypy] → [tool.ty] in pyproject.toml

Read the [tool.mypy] section and convert each key to the ty equivalent:

mypy key	ty equivalent	Notes
python_version	python-version	Rename only
strict	strict	Same
warn_return_any	warn-return-any	Kebab-case
disallow_untyped_defs	disallow-untyped-defs	Kebab-case
ignore_missing_imports	Not needed	ty resolves stubs natively
exclude	exclude	Same
Per-module [[tool.mypy.overrides]]	Drop or convert manually	Note for manual review

Remove the [tool.mypy] section (and any [[tool.mypy.overrides]] sections). Add [tool.ty] with converted keys. Annotate any options that need manual review.

Step 4: Remove mypy.ini

If mypy.ini exists, delete it. Its content should already be in [tool.ty] after Step 3.

Step 5: Remove mypy from dependencies

If mypy appears in pyproject.toml dev/lint dependencies, remove it:

# With uv
uvx --from uv uv remove --dev mypy 2>/dev/null || true

If not using uv, note it for manual removal.

Step 6: Verify migration

Run the new hook to confirm it works:

pre-commit run ty --all-files

If it exits 0, the migration is complete. If it exits non-zero:

• Summarize ty errors
• Suggest addressing them before committing

Step 7: Report

Print a summary of all changes made and list files to commit:

mypy → ty migration complete
=============================
.pre-commit-config.yaml   UPDATED (removed mirrors-mypy, added local ty hook)
pyproject.toml            UPDATED ([tool.mypy] → [tool.ty])
mypy.ini                  DELETED / NOT FOUND

Manual review needed:
  - [[tool.mypy.overrides]] sections were dropped — verify ty handles them
  - Check ty docs for any unsupported mypy options

Files to stage:
  git add .pre-commit-config.yaml pyproject.toml

Agentic Optimizations

Context	Command
Audit only	/migration-patterns:mypy-to-ty --check-only
Apply migration	/migration-patterns:mypy-to-ty --fix
Verify after migration	pre-commit run ty --all-files
Test ty directly	uvx ty check .

Quick Reference

Item	Value
ty docs	https://github.com/astral-sh/ty
Pre-commit hook type	repo: local, entry: uvx ty check
Config section	[tool.ty] in pyproject.toml
Key difference	ty uses kebab-case keys; mypy uses underscore

See Also

• /migration-patterns:black-to-ruff-format — Migrate from black to ruff format
• /migration-patterns:flake8-to-ruff — Migrate flake8/isort to ruff
• /configure:repo — End-to-end repo config driver