Pyright Guide: Installation, Configuration, and Use Cases

Have you ever wanted faster type checking for Python without slowing down your workflow? Tools like MyPy can catch type errors, but they often feel slow or disconnected from the editor experience. This is where Pyright comes in. Pyright is a standards-based static type checker for Python designed for speed and fast feedback. It runs both as a command-line tool and as a language server, enabling real-time diagnostics while you write code. It integrates closely with Microsoft’s Python tooling and works across editors through the Language Server Protocol (LSP).

What is Pyright?

Pyright uses a project-based configuration system that defines which files are analyzed and how imports are resolved. It also allows teams to specify the target Python version and control the level of type-checking strictness. This flexibility makes it easy to begin with basic checks and gradually introduce stricter rules as the codebase matures. Pyright integrates well with CI workflows and scales effectively to large projects, enabling teams to adopt static typing without disrupting existing development practices.

If you want to know the Python basics for building AI Agents, then checkout our FREE course on ABC of coding for building agents.

Purpose and Core Features

Pyright helps developers catch type errors early in Python code. Because Python typing remains optional at runtime, static analysis helps identify issues before execution, such as incorrect argument types, unsafe None access, and invalid assignments. Pyright follows Python’s typing standards and delivers fast feedback even in large codebases.

Pyright analyzes code using a project-wide engine that parses, binds, and type-checks files under configurable rules. It also integrates with editors through a language server, enabling real-time diagnostics during development.

Core features include:

Project-wide analysis: Files are parsed, bound, and type-checked across the project.
Flow-sensitive typing: Types are narrowed based on control flow.
Language server support: Provides real-time diagnostics in editors.
Type completeness checks: Helps validate type information for libraries.
Cross-editor portability: Implemented in TypeScript for consistent tooling support.

Also Read: A Complete Python Tutorial to Learn Data Science from Scratch

Installing Pyright

Pyright is available as a command-line tool and as a language server. The CLI is used for CI and local checks. The language server is used by editors through the Language Server Protocol. Both use the same core engine.

The most common installation method is through npm. A typical setup looks like this:

npm install -g pyright 
pyright --version

You can then run type checks with:

{
  "include": ["."],
  "exclude": ["**/__pycache__", "**/.venv", "**/.git"],
  "typeCheckingMode": "basic",
  "pythonVersion": "3.12"
}

To start the language server directly, use:

pyright-langserver --stdio

Community Python wrappers are also available. These install Node and the Pyright npm package automatically. They do not change the checker itself.

In Visual Studio Code, developers commonly use Pyright through Pylance, which runs Pyright under the hood. You can control type-checking behavior through workspace settings such as python.analysis.typeCheckingMode and python.analysis.diagnosticMode. If you prefer running Pyright directly, you can install the separate Pyright extension.

In Neovim, developers typically run Pyright through the language server. Many setups use nvim-lspconfig to configure it. Neovim starts the server with pyright-langserver, and you can define analysis settings under settings.python.analysis to control strictness and workspace scope.

Other LSP Clients

Pyright works across many editors because it runs as a language server. Any editor that supports the Language Server Protocol (LSP) can start pyright-langserver. The server reads configuration from pyrightconfig.json or the tool.pyright section in pyproject.toml, which keeps type-checking behavior consistent across different tools.

Editors such as Emacs and Sublime Text connect directly to pyright-langserver and handle tasks like environment detection and server startup. Pyright itself still performs all type-checking and diagnostics.

Key characteristics:

Works with any LSP-compliant editor
Uses pyright-langserver as the backend
Honors project configuration files
Provides consistent diagnostics across editors

Configuration with pyrightconfig.json

Pyright provides two main ways to define project configuration. You can place a pyrightconfig.json file at the project root or define a tool.pyright section inside pyproject.toml. If both exist, pyrightconfig.json takes priority.

The configuration focuses on a few core aspects of how Pyright analyzes a project.

Files to analyze

Controlled by include, exclude, and ignore
Files listed in exclude may still be analyzed if they are imported
Files listed in ignore suppress diagnostics

Python environment

Defined by pythonVersion and pythonPlatform
executionEnvironments allows multiple targets
Import resolution can use extraPaths and venv settings

Type-checking strictness

typeCheckingMode defines the baseline level
Strict rules can be enabled for specific files or folders

Diagnostics configuration

Individual report rules can be customized
Severity levels can be none, info, warning, or error

Examples for Common Project Types

The following examples show common Pyright setups. They are opinionated but practical. Each one uses documented options. The goal is to balance signal, performance, and adoption speed.

Single-file script or notebook-style repo

This setup favors fast feedback. It avoids strictness early. It works well for experiments and small tools.

Broad include to catch obvious issues
Basic checking for low friction
Explicit Python version

Package repo with src/ layout and tests

This setup stabilizes imports. It reflects how the package is actually executed. It is common for libraries and services.

Separate src and tests directories
Use a standard type-checking level
Configure executionEnvironments to resolve import paths correctly

{
  "include": ["src", "tests"],
  "exclude": ["**/__pycache__", "**/.venv", ".tox", "dist", "build"],
  "typeCheckingMode": "standard",
  "pythonVersion": "3.12",
  "executionEnvironments": [
    {
      "root": "src",
      "extraPaths": ["src"]
    }
  ]
}

This setup supports scale. It centralizes rules. It allows gradual strict adoption per package.

Shared base config
Per-package overrides
Strict checking only for new code

Root config:

{
  "exclude": ["**/__pycache__", "**/.venv", "**/.git", "**/node_modules"],
  "pythonVersion": "3.12",
  "typeCheckingMode": "standard",
  "reportMissingImports": "error",
  "reportMissingTypeStubs": "none"
}

Package config:

{
  "extends": "../../pyrightconfig.base.json",
  "include": ["src", "tests"],
  "strict": ["src/new_code"],
  "executionEnvironments": [
    { "root": "src", "extraPaths": ["src"] }
  ]
}

Django app

This setup reduces noise. It avoids generated files. It keeps missing types visible but not blocking.

Exclude migrations and static files
Warn on missing stubs
Custom stub directory

{
  "include": ["."],
  "exclude": [
    "**/__pycache__",
    "**/.venv",
    "**/migrations/**",
    "static",
    "media"
  ],
  "typeCheckingMode": "standard",
  "reportMissingTypeStubs": "warning",
  "stubPath": "typings"
}

FastAPI service

This setup bridges toward strict typing. It highlights unknowns without breaking builds.

Standard checking
Warn on unknown types
Good fit for dynamic frameworks

{
  "include": ["app", "tests"],
  "exclude": ["**/__pycache__", "**/.venv"],
  "typeCheckingMode": "standard",
  "reportUnknownParameterType": "warning",
  "reportUnknownVariableType": "warning"
}

These patterns are starting points. They are meant to evolve. Pyright works best when strictness increases gradually.

When to choose Pyright?

Scenario

Why Choose Pyright

Very fast type checking

Pyright is optimized for performance and delivers quick results even in large projects.

Responsive editor feedback

It performs incremental analysis, so errors appear quickly while you type.

Consistent results in editor and CI

The CLI and the language server use the same core analyzer, keeping diagnostics consistent across environments.

Gradual adoption of strict typing

Teams can start with basic checks and tighten rules as the codebase evolves.

Large codebases

Its project-based configuration and staged analysis scale well across many files.

Visual Studio Code with Pylance

Pylance runs on Pyright and provides rich, real-time diagnostics and completions.

Works across multiple editors

Editors such as Neovim, Emacs, and Sublime Text can run Pyright through the Language Server Protocol.

Modern Python typing support

Pyright closely follows the official typing standard and supports advanced narrowing and generics.

Performance-focused teams

Teams that value fast feedback and predictable behavior across tools benefit the most.

Also Read: Fundamentals of Python Programming for Beginners

Conclusion

Pyright offers a fast, standards-based approach to static type checking in Python. It combines strong analysis with responsive editor integration and a flexible project configuration system. From small scripts to large monorepos, it adapts to different team needs and levels of strictness. Its language server architecture delivers consistent diagnostics across editors and CI environments. With clear configuration options and gradual adoption paths, teams can introduce stronger typing without disrupting existing workflows. For developers who value performance, scalability, and modern typing support, Pyright provides a practical foundation for building safer and more maintainable Python codebases.

Hi, I am Janvi, a passionate data science enthusiast currently working at Analytics Vidhya. My journey into the world of data began with a deep curiosity about how we can extract meaningful insights from complex datasets.