Coming from mypy or pyright

This guide helps you migrate a project from mypy or pyright to ty.

Migration tips

• mypy disables an error code with # type: ignore[code]; pyright suppresses a single line with # pyright: ignore[reportXyz]; ty's equivalent is # ty: ignore[rule]. See this page for more information about suppression comments.
• mypy's disable_error_code and pyright's reportXyz = "none" both correspond to setting <rule> = "ignore" under [tool.ty.rules]. See this section for details.
• Severities in ty are ignore, warn, error. Pyright's "information" level and basedpyright's "hint" level have no direct ty equivalent — use warn for both.
• If you are looking for the equivalent of disallow_untyped_defs / no-untyped-def (mypy) or reportMissingParameterType, reportUnknownParameterType (pyright), check out this FAQ entry.
• Unlike mypy, ty checks the bodies of unannotated functions unconditionally, so there is no ty rule corresponding to mypy's check_untyped_defs setting. The equivalent pyright setting is analyzeUnannotatedFunctions = true.

Stricter checking with ty

For both mypy and pyright, "strict" mode enables several error codes that are otherwise disabled by default, but also makes fundamental changes to the way type inference and type checking works. Mypy's strict mode includes --check-untyped-defs, for example, without which unannotated functions are left unchecked; pyright's strict mode includes strictListInference, without which [1, "foo"] will be inferred as having type list[Unknown] rather than list[int | str] or similar.

ty's default mode is currently stricter by default than either mypy or pyright in many ways. ty does not have flags such as --check-untyped-defs or strictListInference, because these are ty's default behaviour and are not currently configurable. Meanwhile, nearly all ty rules are enabled by default, and the ones that are disabled by default are usually in that category because they are either very opinionated or have many false positives.

Recommended configuration

To enable all ty rules at once with the error severity, you can simply use --error=all, but we wouldn't recommend it. Instead, you can currently approximate something similar to the --strict mode of other type checkers with the following configuration:

[tool.ty.rules]
dynamic-function-decorator-return = "error"
missing-type-argument = "error"
possibly-unresolved-reference = "warn"
unsound-return-statement = "error"

[tool.ruff.lint]
extend-select = ["ANN", "PYI"]
preview = true

This configuration:

• Enables ty's disabled-by-default dynamic-function-decorator-return, missing-type-argument, possibly-unresolved-reference, and unsound-return-statement rules
• Extends Ruff's default rules with the ANN and PYI rule categories, both of which are focussed on type-annotating your code more effectively
• Enables Ruff's preview mode so that PYI033 also checks .py files

An even stricter configuration -- that goes beyond what mypy and pyright check for in their default --strict mode in several respects -- might look like this:

[tool.ty.rules]
blanket-ignore-comment = "error"
dynamic-function-decorator-return = "error"
missing-type-argument = "error"
possibly-unresolved-reference = "warn"
unsound-assignment = "error"
unsound-return-statement = "error"
unsound-yield = "error"
unsupported-dynamic-base = "warn"

# NOTE: the following rules are known to have a significant number of false positives,
# which is mostly unavoidable. Enable them at your own risk!
division-by-zero = "warn"
possibly-missing-attribute = "warn"
possibly-missing-import = "warn"

[tool.ty.analysis]
strict-literal-narrowing = true
strict-generic-narrowing = true

[tool.ruff.lint]
extend-select = ["ANN", "PYI", "PGH003"]
preview = true

Note that several checks in mypy and pyright are not yet implemented in ty. See the rule mapping table below for more details.

Mapping pyright/mypy rules to ty/Ruff rules

How to read this table

• ty or Ruff rule: the canonical name, as listed in Rules if it is a ty rule. Configure ty rules under [tool.ty.rules]. Where Ruff provides equivalent coverage for a check that has no ty rule, the relevant Ruff rule or rule group is linked instead.
• Mypy error code: the value passed to # type: ignore[<code>] or disable_error_code. Some ty rules surface as one of mypy's catch-all codes (misc, assignment, valid-type); these mappings are deliberately broad.
• Pyright diagnostic: the report* setting in pyrightconfig.json or [tool.pyright].

A diagnostic may appear in multiple rows when it covers distinct cases. A blank cell means no direct equivalent exists in that checker (the diagnostic is either not emitted, or is folded into a broader category that already appears for another ty rule).

Rules

The full list of ty rules — including those without a direct equivalent above — is in Rules. Contributions to extend this mapping are welcome via pull request to the ty repository; see issue #2111 for context.