/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

Read .pre-commit-config.yaml and locate any mirrors-mypy or mypy entries.
Read pyproject.toml and extract the [tool.mypy] section.
Check for mypy.ini.

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

mypy-to-ty