# pyright: Python Static Type Checker by Microsoft


pyright is a static type checker and language server 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)
- [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