How to try the ty type checker

This guide shows you how to try out ty, a static type checker and language server, in your project.

Prerequisites

To proceed, you’ll need uv.

Run ty from the command line

uvx ty check

This checks all Python files in the working directory or project.

Try ty online

ty has an online playground for trying it out on snippets or small projects. The playground is useful for sharing code examples with others.

Use the ty language server

ty includes a Language Server Protocol (LSP) implementation compatible with modern editors.

VS Code and Cursor

Install the official ty extension from the Visual Studio Marketplace.

Then disable the language server from the Python extension to avoid running two language servers. Add this to your settings.json:

{
  "python.languageServer": "None"
}

Neovim

For Neovim 0.10, use a compatible older release of nvim-lspconfig:

require('lspconfig').ty.setup({
  settings = {
    ty = {
      -- ty language server settings go here
    }
  }
})

For Neovim 0.11+, install nvim-lspconfig or define the ty server configuration manually before using vim.lsp.config:

-- Optional: Only required if you need to update the language server settings
vim.lsp.config('ty', {
  settings = {
    ty = {
      -- ty language server settings go here
    }
  }
})

-- Required: Enable the language server
vim.lsp.enable('ty')

Zed

ty is included with Zed out of the box. Enable ty and disable basedpyright by adding this to your settings.json:

{
  "languages": {
    "Python": {
      "language_servers": ["ty", "!basedpyright", "..."]
    }
  }
}

PyCharm

PyCharm has native ty support:

1. Open Python | Tools | External Tools in Settings and turn on ty.
2. Choose a Lookup method: Sdk checks the interpreter, then $PATH, then uvx; Path checks $PATH, then uvx; uvx runs ty through uv.
3. Use the gear icon in the ty row to choose editor features.

See JetBrains’ Python tools settings for the current controls.

Other editors

ty works with any editor that supports the Language Server Protocol. Start the language server with:

ty server

Refer to your editor’s documentation for connecting to an LSP server.

Troubleshooting

ty cannot find standard library modules

If ty reports that a standard library import is unresolved, check the Python target in pyproject.toml. For example, tomllib requires Python 3.11, so importing it unconditionally fails a check targeting Python 3.10. ty infers the target from requires-python unless an explicit setting overrides it; see Python version configuration.

Set the minimum Python version your project actually supports:

[project]
requires-python = ">= 3.10"

You can also override the version on the command line without changing your project metadata:

ty check --python-version 3.12

ty cannot find installed third-party packages

If ty’s LSP shows from requests import ... but cannot resolve members from the module, the virtual environment may not exist or ty may not be finding it. Run uv sync to create the environment, then restart the language server.

If your virtual environment is in a non-standard location, point ty at it explicitly:

ty check --python .venv

In editor settings, you can configure this path so the language server finds packages automatically. In VS Code and Cursor, configure the environment through ty’s editor configuration:

{
  "ty.configuration": {
    "environment": {
      "python": ".venv"
    }
  }
}

ty shows errors that mypy or pyright do not

ty is in beta and implements some type-checking rules differently. If a diagnostic looks wrong, check whether the rule name (shown in brackets, like [invalid-argument-type]) can be suppressed or downgraded in your configuration:

[tool.ty.rules]
import-not-found = "warn"

Warnings still fail the default CLI check. Pass --exit-zero-on-warning if warnings should remain advisory. Report unexpected diagnostics on the ty issue tracker.