Start Using ty in Python Now

Python is a dynamically typed language, so it requires third-party tools to performtype checking and other kinds ofstatic code analysis. Recently,ty joined the club of external type-checking tools for Python. Despite being created by a private company,Astral, the tool itself remains open source and MIT-licensed.

Although ty is mostly written inRust, you don’t need the Rust compiler or its execution environment to type check your Python projects with it. To quickly get started with ty, you can install it directly fromPyPI withpip, preferably within an activatedvirtual environment:

(venv)$python-mpipinstallty

As long as you’re on one of the three major operating systems—Windows, macOS, or Linux—this command will bring a hefty binary script calledty into your virtual environment. The script is already compiled tomachine code suitable for your platform with all the necessary dependencies baked in, so you can run it directly, just like any other command-line program.

To verify the installation, run the following command in yourterminal emulator app:

(venv)$ty--versionty 0.0.1-alpha.21

You should see a version number similar to the one above appear in the output. Alternatively, if that doesn’t work, then try to executety as a Python module using the interpreter’s-m option:

(venv)$python-mty--versionty 0.0.1-alpha.21

When you do, Python runs a tinywrapper script that looks for thety binary executable in your path and invokes it for you.

Note that thepip install command only installs ty into the given virtual environment, which is usually associated with a specific project. To make ty available globally from any folder on your computer, you’ll need to use a different approach. Check out theofficial documentation for more installation options.

From now on, you won’t see the virtual environment’s name (venv) in the command prompts for the rest of this tutorial. To keep the code blocks concise, it’ll be assumed that ty is already installed globally and available in your system’s path.

Alright. It’s time for the fun part: letting ty scrutinize some Python code to catch bugs before they sneak in.

Catch Typing Errors With ty

Thecommand-line interface of ty is pretty minimal and straightforward, as you’ll notice when you runty without providing any subcommands or options:

$tyAn extremely fast Python type checker.Usage: ty <COMMAND>Commands:  check    Check a project for type errors  server   Start the language server  version  Display ty's version  help     Print this message or the help of the given subcommand(s)Options:  -h, --help     Print help  -V, --version  Print version

The highlighted line indicates the only subcommand you really need to care about:ty check. It runs a number of type checks against your codebase using a comprehensive set ofbuilt-in rules, which you can fine-tune later to match your preferences.

To reveal more details about thety check subcommand, use the--help flag as follows:

$tycheck--helpCheck a project for type errorsUsage: ty check [OPTIONS] [PATH]...Arguments:  [PATH]...          List of files or directories to check [default: the project root]Options:      --project <PROJECT>          Run the command within the given project directory.          (...)

This displays a ton of options, which might feel a bit intimidating at first. Fortunately, you can ignore all of them for now by relying on ty’s sensible defaults and aclever discovery of Python code. The help page above will become more useful as you gain some experience with ty.

When you run the barety check command without any options from theroot folder of your project, it’llrecursively scan all the files and directories within that project. For starters, you can try running it against the source code of the popularDjango framework to see how ty works in a real-world scenario.

You can useGit to clone Django’s source code from GitHub if you haven’t already. Don’t forget to install Django and its dependencies into a virtual environment afterward:

$gitclonegit@github.com:django/django.git$cddjango/$python-mvenv.venv/--promptdjango$source.venv/bin/activate(django)$python-mpipinstall.(django)$deactivate

Now, while you’re still in the top-leveldjango/ folder, run thety check command as follows:

$tycheckWARN ty is pre-release software and not ready for production use.⮑ Expect to encounter bugs, missing features, and fatal errors.Checking ----------------------------------------------------- 2871/2871 files(...)Found 14249 diagnostics

Notice the prominent warning message that ty displays up top, serving as a reminder that this tool isn’t yet suitable for production environments. In this case, ty issued numerous errors and warnings, collectively calleddiagnostics, which have been omitted for brevity.

By the way, it’s worth appreciating how ty checks 2,871 Python files—averaging 175lines of code each—in just a few seconds. Some of this time is actually spent printing the diagnostic messages on the screen. When you use ty’ssilent mode (-qq), the measured time drops even further:

$timetycheck-qqreal    0m3.804suser    0m12.224ssys     0m1.531s

The discrepancy between the real and user times reported by thetime command is a good thing. It indicates that ty leverages yourmulti-core processor architecture forparallel execution.

And here’s what a sample error message displayed by ty looks like by default:

 1error[missing-argument]: No arguments provided for required parameters `year`, `month`, `day` of function `__new__` 2  --> django/utils/dateparse.py:78:20 3   | 476 |         if match := date_re.match(value): 577 |             kw = {k: int(v) for k, v in match.groupdict().items()} 678 |             return datetime.date(**kw) 7   |                    ^^^^^^^^^^^^^^^^^^^ 8   | 9info: rule `missing-argument` is enabled by default

On most terminals, this output is colorful and resembles Ruff’s, which ty is based upon. In fact, the new type checker includesRuff as a submodule on GitHub, meaning much of ty’s core implementation is developed within the Ruff codebase.

The structure of the above error message is the following:

• Line 1 contains theseverity level, which can beerror,warning, orinfo, followed by arule name in square brackets identifying the type of issue. The line ends with a human-readabledescription.
• Line 2 indicates thelocation consisting of the file path, line number, and column number, which tell you exactly where the issue was found.
• The following lines reveal a line-numberedcode snippet, which shows a few surrounding lines of code for context. The caret symbol (^) highlights the exact code segment related to the issue.
• Line 9 containsadditional notes, such as why a particular rule was triggered.

Sometimes, this might be too much information shown at once. To reduce the noise, you can tell ty to use a more concise format:

$tycheck--output-formatconciseWARN ty is pre-release software and not ready for production use.⮑ Expect to encounter bugs, missing features, and fatal errors.Checking ----------------------------------------------------- 2846/2846 filesdjango/apps/config.py:197:27: error[invalid-argument-type] Argument to function `issubclass` is incorrect: Expected `type`, found `None | (@Todo & ~None) | Unknown`django/apps/registry.py:87:26: error[not-iterable] Object of type `Unknown | None` may not be iterable  ⋮tests/xor_lookups/tests.py:86:13: error[unresolved-attribute] Type `<class 'Number'>` has no attribute `objects`Found 14249 diagnostics

With the--output-format switch, you can change the output style to a compact format that fits each diagnostic message on a single line. This can be particularly helpful for parsing the output programmatically inCI/CD pipelines, for example, with thegrep command.

Each line still contains the corresponding rule name, allowing you to override how ty behaves by default. Next up, you’ll learn what you can do with this information.

Tweak the Type Checking Rules

Out of the box, ty assigns a default severity level to each of its rules, which you can view in thereference documentation. Here are a couple of examples:

Depending on therule’s level, ty uses different colors to display the violation and takes a slightly different action. When the command detects an error, it returns with anexit code of 1. On the other hand, if there are only warnings and you haven’t used the--error-on-warning flag, then the command returns with an exit code of 0. Finally, problems with theignore level aren’t reported.

By knowing therule names, you can change their default levels using the corresponding command-line options. Specifically, you can elevate or degrade the default levels with the--error,--warn, and--ignore options. Each of these options can appear more than once within a single invocation:

$tycheck--ignoreunresolved-attribute\--ignore=unresolved-import\--warndivision-by-zero\--errordeprecated

As you can see, listing the new rule levels directly on the command line can quickly get cumbersome and error-prone. Plus, this approach isn’t easily repeatable across a team of developers. You’ll often prefer tweaking the rules for your project using a persistentconfiguration file, such aspyproject.toml orty.toml:

# ...[tool.ty.rules]unresolved-attribute="ignore"unresolved-import="ignore"division-by-zero="warn"deprecated="error"

If you have both files in your project, thenty.toml takes precedence overpyproject.toml. Note that you can also include a user-level configuration shared across multiple projects that can override the individual rules with their own configuration.

Both the command-line switches and the configuration files have aglobal effect on ty’s behavior across your entire project. To suppress rules only in aspecific location in your code, you canwrite comments that start with a special marker on a given line. This marker comes in a few flavors:

• # ty: ignore
• # ty: ignore[rule1]
• # ty: ignore[rule1, rule2, rules3, ...]

When you don’t specify any rule names in square brackets, then ty will disableall rules affecting that line. Otherwise, it’ll only disable the listed rules. Note that you can’t elevate rules to errors or warnings with comments like you did before with the command-line switches—you can only ignore them.

If the affectedexpression or statement spans multiple lines, then try putting your comment either on its first or last line:

importwarnings@warnings.deprecated("Use the new_adder() instead")deflegacy_adder(x,y):returnx+ylegacy_adder(# ty: ignore42,555)legacy_adder(42,555)# ty: ignore

Unfortunately, commenting such multiline expressions doesn’t always work as expected at the moment. Quirks like this are to be expected in a pre-release version of ty.

As mentioned earlier, the bare# ty: ignore marker comment sets the level for all potential rule violations that might occur on the chosen line of code. Meanwhile, the official documentation recommends always explicitly listing one or more rules in square brackets:

# ...typeNumber=int|floatdefnew_adder(x:Number,y:Number)->Number:returnx+ynew_adder(a=42,b=555)# ty: ignore[unknown-argument, missing-argument]

You use a comma to separate the listed rule names. This approach helps avoid potential ambiguity and prevents unintentional silencing of important red flags in your code.

At this point, you know a lot about tweaking the output and the default rule levels in ty. However, you glossed over a few important details about its convenient module discovery mechanism, which you’ll explore in the next section.

Narrow Down the Discovery Scope

You can narrow down the scope of the search by specifying particular files or directories aspositional arguments, or by changing yourworking directory to a subdirectory. Conversely, by using the--exclude option, you can defineglob patterns to be exempt from type checking, which can reduce unnecessary checks on files that are irrelevant to your current task:

$cdtests/$tycheckauth_tests/runtests.py--exclude"**/test_*.py"(...)Found 10 diagnostics

This cuts down the output significantly, yet it’s still pretty verbose.

Regardless of where in your project you run thety check command, the tool detects the configuration files, such aspyproject.toml, and remains fully aware of the overallproject structure. It supports bothsrc and flat layouts, among others. This is crucial for resolving imports correctly, letting you operate on relative paths.

When scanning, ty looks for plain Python files (.py),stub files (.pyi) with type signatures, and evenJupyter Notebooks (.ipynb). At the same time, it skips commonly ignored directories like virtual environments, which often contain Python’s ownstandard library and any installed third-party packages. You don’t want to type check those directly, after all.

However, since your code often depends on these third-party packages, the type checker still needs to access their source code—or their accompanying type stubs—to verify if yourown code uses them correctly. Thediscovery of third-party modules in ty is also automated and involves multiple steps. Here are a few common scenarios:

• Active Environment: If you runty check from within an activatedvirtual environment or aConda environment, then ty will automatically detect and include the packages installed in that environment.
• Inactive Environment: If your project has a virtual environment stored in a local folder named.venv/ (prefixed with a dot), then ty will recognize it even if you haven’t activated that environment yourself. Note that ty doesn’t currently recognize the equally commonvenv/ folder as a virtual environment during the discovery phase. However, it ignoresvenv/ when scanning for files to type check.
• Custom Interpreter or Environment: You can explicitly provide the path to a givenpython executable or a virtual environment’s home folder by using the--python option, but you can specify it only once.
• System Python: Finally, ty falls back on your system Python to find any missing modules.

Apart from discovering first-party and third-party modules, ty makes a best effort to determine a suitablePython version for your project based on various configuration options, metadata, and the environment. At the same time, you can override it with the--python-version switch, providing a custom Python version as low as3.7:

$tycheck--python-version3.7WARN ty is pre-release software and not ready for production use.⮑ Expect to encounter bugs, missing features, and fatal errors.Checking ----------------------------------------------------------- 1/1 fileserror[invalid-syntax] --> python_version.py:3:1  |1 | from typing import Literal2 |3 | type Size = Literal["S", "M", "L", "XL"]  | ^^^^ Cannot use `type` alias statement on Python 3.7 (syntax was added in Python 3.12)  |info: Python 3.7 was assumed when parsing syntax because it was specified on the command lineFound 1 diagnostic

This gives you control over which elements of the Python syntax and which modules in the standard library are enabled.

Similarly, you can use the--platform switch to enforce the desired operating system mode, effectively restricting the visibility of platform-specific objects in Python. This makescross-platform type checking easier:

$tycheck--platformwin32WARN ty is pre-release software and not ready for production use.⮑ Expect to encounter bugs, missing features, and fatal errors.Checking ----------------------------------------------------------- 1/1 filesinfo[revealed-type]: Revealed type --> cross_platform.py:9:13  |7 |     x = "macOS or Linux"8 |9 | reveal_type(x)  |             ^ `Literal["Windows"]`  |Found 1 diagnostic

The valid values match those of Python’ssys.platform attribute. When left unspecified, ty defaults to your native operating system. Alternatively, you can use the special valueall to type check every platform-specific branch of code.

Finally, ty recognizes patterns defined in.gitignore and.ignore files. This means any files or directories listed in these files will be skipped during checks, just like withexclusions in the configuration. You can use.gitignore or.ignore to manage ignored files globally for your project, and ty will automatically honor those patterns unless you override this behavior with specific command-line options or configuration settings.

Beware of Limitations and Gotchas

While ty is exciting, remember that it’s still preview software. Here are a few important things to be aware of:

• Not production-ready: Stick to mature tools likemypy, Microsoft’sPyright, or Meta’sPyre for mission-critical projects.
• Bugs and missing features: Core functionality is still evolving, and quirks are inevitable.
• Incomplete ecosystem support: IDE integration is limited outside of VS Code, and some typing features aren’t fully implemented yet.
• Rapid changes: The tool is moving fast, so behavior and features may shift between versions.

That said, ty shines when you need fast, lightweight, and intuitive feedback in personal or experimental projects. Its shortcomings are likely to shrink over time, so keep an eye on updates!

Conclusion

Astral’s ty offers a fresh take on Python type checking, emphasizingspeed anddeveloper experience. While it’s still in preview and not yet ready to replace mature tools in production, ty’s fast feedback loop and intuitive output make it a compelling option for experimentation and personal projects.

In this tutorial, you’ve learned how to:

• Installty from PyPI for immediate use
• Run thety check command to scan projects for type errors
• Read and interpret ty’s structured, color-coded diagnostics
• Configure rules globally or inline to fine-tune checks
• Limit scope and exclude files for faster, focused analysis
• Override Python version and platform to test cross-environment compatibility

Keep in mind that ty is evolving rapidly. By the time you read this, new features may have landed, bugs may have been fixed, and IDE support may have improved. So stay curious, keep your tools updated, and don’t hesitate to explore the latest developments in itsdocumentation andGitHub repository.

Frequently Asked Questions

Now that you have some experience with ty in Python, you can use the questions and answers below to check your understanding and recap what you’ve learned.

These FAQs are related to the most important concepts you’ve covered in this tutorial. Click theShow/Hide toggle beside each question to reveal the answer.

Take the Quiz: Test your knowledge with our interactive “Astral's ty Type Checker for Python” quiz. You’ll receive a score upon completion to help you track your learning progress:

---

Interactive Quiz

Astral's ty Type Checker for Python

Test your knowledge of Astral's ty—a blazing-fast, Rust-powered Python type checker. You'll cover installation, usage, rule configuration, and the tool's current limitations.