# pyright: Python Static Type Checker by Microsoft


pyright is a static type checker and [language server](https://pydevtools.com/handbook/explanation/what-is-a-python-language-server.md) for Python, built and maintained by Microsoft. It analyzes type annotations to detect bugs before runtime and provides editor features like autocompletion, hover information, and go-to-definition.

pyright powers the [Pylance extension](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) for Visual Studio Code. Pylance is closed-source and adds features on top of pyright's open-source language server, but pyright itself can be used with any editor that supports LSP.

## When to use pyright

pyright is a strong choice for teams that want real-time type feedback in their editor, especially in VS Code through the Pylance extension. Its aggressive type inference catches bugs in unannotated code that [mypy](https://pydevtools.com/handbook/reference/mypy.md) would skip by default.

Teams already using mypy as a CLI type checker have no urgent reason to switch. pyright and mypy can coexist: use Pylance in the editor for instant feedback and mypy in CI for type checking. For a detailed comparison, see [How do mypy, pyright, and ty compare?](https://pydevtools.com/handbook/explanation/how-do-mypy-pyright-and-ty-compare.md).

For a newer, faster alternative, see [ty](https://pydevtools.com/handbook/reference/ty.md), which is significantly faster than both mypy and pyright and offers a "gradual guarantee" that adding annotations to working code never introduces new errors. ty is still in beta.

## Key Features

- Type inference on unannotated code: pyright checks all code by default, including functions without type annotations, using inferred types. Five strictness levels (`off`, `basic`, `standard`, `strict`, `all`) control how aggressively it flags issues.
- On-demand type computation: computes types lazily rather than analyzing everything upfront. Historically this made pyright 3-5x faster than mypy; mypy's 1.18+ mypyc-compiled builds have closed the gap and often beat pyright on current versions.
- Watch mode: `pyright --watch` rechecks files as they change, providing continuous feedback during development.
- Flow analysis: tracks variable types through control flow paths, narrowing types after `isinstance` checks, `is None` guards, and other patterns.
- Standards-forward: often implements new typing PEPs before other checkers, making it useful for projects using the latest typing features.
- Type stub integration: works with typeshed and custom stub files for libraries that don't ship inline type annotations.

## Configuration

pyright reads configuration from `pyrightconfig.json` or `pyproject.toml` (under `[tool.pyright]`).

```toml {filename="pyproject.toml"}
[tool.pyright]
pythonVersion = "3.12"
typeCheckingMode = "standard"
reportMissingTypeStubs = false
```

The `typeCheckingMode` setting controls overall strictness:

| Mode | Behavior |
|---|---|
| `off` | No type checking |
| `basic` | Minimal checks, few false positives |
| `standard` | Default. Checks most code, flags common errors |
| `strict` | Requires annotations on all public functions, flags more issues |
| `all` | Every diagnostic enabled |

pyright also supports execution environments for per-directory settings, which is useful for monorepos where different packages need different configurations:

```json {filename="pyrightconfig.json"}
{
  "executionEnvironments": [
    { "root": "src/backend", "pythonVersion": "3.11" },
    { "root": "src/scripts", "pythonVersion": "3.12" }
  ]
}
```

## Installation and Usage

The quickest way to run pyright is with [uvx](https://pydevtools.com/handbook/reference/uv.md):

```bash
uvx pyright src/
```

For project use, add pyright as a development dependency:

```bash
uv add --dev pyright
uv run pyright src/
```

Common command-line options:

```bash
# Check with a specific config file
pyright --project ./pyrightconfig.json

# Watch mode for continuous checking
pyright --watch

# Output as JSON for CI integration
pyright --outputjson src/
```

## Editor Integration

VS Code: install the [Pylance extension](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance), which bundles pyright and adds autocompletion, signature help, auto-imports, and rename refactoring. Pylance is closed-source but free.

Other editors: pyright's open-source language server works with any editor that supports LSP. Run `pyright --langserver` or `pyright-langserver --stdio` to start it. Neovim users can configure it through `nvim-lspconfig`; Emacs users through Eglot or lsp-mode.

## Pros

- On-demand type computation historically outran [mypy](https://pydevtools.com/handbook/reference/mypy.md) by 3-5x; mypy's 1.18+ mypyc-compiled builds have closed that gap, and [ty](https://pydevtools.com/handbook/reference/ty.md) is now significantly faster than both
- Best-in-class VS Code integration through the Pylance extension
- Checks unannotated code by default, catching bugs that mypy skips
- Weekly releases with early adoption of new typing PEPs
- Granular configuration with per-directory execution environments for monorepos

## Cons

- Aggressive inference on unannotated code can produce false positives in highly dynamic code
- Requires Node.js runtime (written in TypeScript)
- Pylance (the VS Code extension) is closed-source, so editor features beyond basic LSP are VS Code-only

## Learn More

- [How do mypy, pyright, and ty compare?](https://pydevtools.com/handbook/explanation/how-do-mypy-pyright-and-ty-compare.md)
- [Does Ruff support type checking?](https://pydevtools.com/handbook/explanation/does-ruff-support-type-checking.md)
- [How to configure VS Code for type checking in a uv project](https://pydevtools.com/handbook/how-to/how-to-configure-vs-code-for-type-checking-in-a-uv-project.md)
- [How to migrate from pyright to ty](https://pydevtools.com/handbook/how-to/how-to-migrate-from-pyright-to-ty.md)
- [How to gradually adopt type checking in an existing Python project](https://pydevtools.com/handbook/how-to/how-to-gradually-adopt-type-checking-in-an-existing-python-project.md)
- [How to configure Claude Code with a Python type checker](https://pydevtools.com/handbook/how-to/how-to-configure-claude-code-with-a-python-type-checker.md)
- [Official pyright Documentation](https://microsoft.github.io/pyright/#/)
- [Pylance Extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
- [pyright GitHub Repository](https://github.com/microsoft/pyright)
- [mypy](https://pydevtools.com/handbook/reference/mypy.md) reference
- [ty](https://pydevtools.com/handbook/reference/ty.md) reference
- [basedpyright](https://pydevtools.com/handbook/reference/basedpyright.md) — a faster, aggressive fork of pyright