Skip to content

ty

GitHub stars autofix sarif GitHub release (latest SemVer) GitHub last commit GitHub commit activity GitHub contributors

ty is an extremely fast Python type checker and language server written in Rust by Astral (the creators of Ruff and uv).

Key features:

  • High Performance: Built from the ground up in Rust for blazing-fast type checking and language server operations
  • Incremental Analysis: Salsa-based query system providing instant diagnostics on save or edit
  • Language Server Support: Full Language Server Protocol (LSP) implementation supporting code completion, navigation, and hover documentation
  • Advanced Type System: Features first-class intersection types, advanced type narrowing, and sophisticated reachability analysis
  • Gradual Adoption: Checks unannotated code bodies by default with flexible configuration options and suppression comments

ty documentation

ty - GitHub

Configuration in MegaLinter

Variable Description Default value
PYTHON_TY_ARGUMENTS User custom arguments to add in linter CLI call
Ex: -s --foo "bar"
PYTHON_TY_COMMAND_REMOVE_ARGUMENTS User custom arguments to remove from command line before calling the linter
Ex: -s --foo "bar"
PYTHON_TY_FILTER_REGEX_INCLUDE Custom regex including filter
Ex: (src\|lib)
⚠️ Not available with PYTHON_TY_CLI_LINT_MODE = project		 Exclude no file
PYTHON_TY_FILTER_REGEX_EXCLUDE Custom regex excluding filter
Ex: (test\|examples)
⚠️ Not available with PYTHON_TY_CLI_LINT_MODE = project		 Exclude no file
PYTHON_TY_CLI_LINT_MODE Override default CLI lint mode
- file: Calls the linter for each file
- list_of_files: Call the linter with the list of files as argument
- project: Call the linter from the root of the project		 list_of_files
PYTHON_TY_FORWARD_EXCLUDED_DIRECTORIES In project CLI lint mode, forward excluded directories (EXCLUDED_DIRECTORIES + ADDITIONAL_EXCLUDED_DIRECTORIES, and .gitignored directories when IGNORE_GITIGNORED_FILES is true) to the linter through its native exclusion arguments or generated ignore/config files true
PYTHON_TY_FILE_EXTENSIONS Allowed file extensions. "*" matches any extension, "" matches empty extension. Empty list excludes all files
Ex: [".py", ""]		 [".py", ".pyi"]
PYTHON_TY_FILE_NAMES_REGEX File name regex filters. Regular expression list for filtering files by their base names using regex full match. Empty list includes all files
Ex: ["Dockerfile(-.+)?", "Jenkinsfile"]		 Include every file
PYTHON_TY_PRE_COMMANDS List of bash commands to run before the linter None
PYTHON_TY_POST_COMMANDS List of bash commands to run after the linter None
PYTHON_TY_UNSECURED_ENV_VARIABLES List of env variables explicitly not filtered before calling PYTHON_TY and its pre/post commands None
PYTHON_TY_CONFIG_FILE ty configuration file name
Use LINTER_DEFAULT to let the linter find it		 ty.toml
PYTHON_TY_RULES_PATH Path where to find linter configuration file Workspace folder, then MegaLinter default rules
PYTHON_TY_DISABLE_ERRORS Run linter but consider errors as warnings false
PYTHON_TY_DISABLE_ERRORS_IF_LESS_THAN Maximum number of errors allowed 0
PYTHON_TY_TIMEOUT_SECONDS Maximum duration in seconds of the linter run, after which the linter process and its child processes are killed and reported as an error (exit code 124). Overrides LINTER_TIMEOUT_SECONDS. 0 disables the timeout 300
PYTHON_TY_CLI_EXECUTABLE Override CLI executable ['ty']

IDE Integration

Use ty in your favorite IDE to catch errors before MegaLinter !

IDE Extension Name Install
Visual Studio Code ty Install in VSCode

MegaLinter Flavors

This linter is available in the following flavors

Flavor Description Embedded linters Info
all Default MegaLinter Flavor 134 Docker Image Size (tag) Docker Pulls
cupcake MegaLinter for the most commonly used languages 100 Docker Image Size (tag) Docker Pulls
python Optimized for PYTHON based projects 70 Docker Image Size (tag) Docker Pulls

Behind the scenes

How are identified applicable files

  • File extensions: .py, .pyi

How the linting is performed

ty is called once on the whole project directory (project CLI lint mode)

  • filtering can not be done using MegaLinter configuration variables,it must be done using ty configuration or ignore file (if existing)
  • VALIDATE_ALL_CODEBASE: false doesn't make ty analyze only updated files

Example calls

ty check myfile.py

ty check --config-file ty.toml myfile.py

Help content

An 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
  explain  Explain rules and other parts of ty
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Installation on mega-linter Docker image

  • Dockerfile commands : 
    # renovate: datasource=pypi depName=ty
ARG PIP_TY_VERSION=0.0.100

Installation without Docker (native mode)

This linter can run without Docker, see native mode.

  • Install method: Python package (isolated virtual environment)
  • Requires the python runtime >=3.8
NATIVE_LINTERS: [PYTHON_TY]
Platform Support
Linux (x86-64) ✅
Linux (ARM64) ✅
macOS (Intel) ✅
macOS (Apple Silicon) ✅
Windows (Git Bash) ✅

Known errors and resolutions

When this linter fails for a known non-lint reason (remote service unavailable, malformed config, missing credentials, etc.), MegaLinter detects the pattern below in the linter output and surfaces the matching guidance.

PYTHON_TY_ERROR_CONFIG_PARSE

Detection pattern (regex):

(Error loading configuration file|is not a valid `ty\.toml`|TOML parse error)

Resolution guidance:

ty could not parse its configuration file (`ty.toml` or `pyproject.toml`).
Resolutions:
  - Validate the TOML syntax of your ty config.
  - Ensure configuration options match the pinned ty version schema.

PYTHON_TY_ERROR_IMPORT_NOT_FOUND

Detection pattern (regex):

(error\[import-not-found\]|Cannot resolve imported module)

Resolution guidance:

ty could not resolve a third-party or local module import (`import-not-found`).
Because ty runs inside MegaLinter's isolated container, it will not see packages installed only in your project's environment unless configured.
Resolutions:
  - Install your project dependencies before linting and point ty to that environment via `PYTHON_TY_PRE_COMMANDS` or `--python` in `PYTHON_TY_ARGUMENTS`:
      PYTHON_TY_PRE_COMMANDS:
        - command: "pip install -r requirements.txt"
          venv: ty
          continue_if_failed: false
  - For first-party modules outside the repository root (e.g. `.automation/` or `src/`), add them under `[environment] extra-paths` in `ty.toml` or `[tool.ty.environment]` in `pyproject.toml`.
  - To ignore missing-import errors when external stubs/packages are unavailable, set `import-not-found = "ignore"` under `[rules]` (`[tool.ty.rules]` in `pyproject.toml`).

Comments