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?

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.