Basedpyright Type Checking

Basedpyright is a fork of Pyright with additional features and stricter defaults, designed for maximum type safety and performance.

When to Use This Skill

Use this skill when...	Use another tool instead when...
Setting up type checking for Python	Formatting code (use ruff format)
Configuring strict type validation	Linting for style issues (use ruff check)
Comparing type checkers (basedpyright vs mypy)	Detecting unused code (use vulture/deadcode)
Setting up LSP for type-aware editor support	Running tests (use pytest)

Installation

Via uv (Recommended)

# Install globally
uv tool install basedpyright

# Install as dev dependency
uv add --dev basedpyright

# Run with uv
uv run basedpyright

Via pipx

pipx install basedpyright

Basic Usage

# Check entire project
basedpyright

# Check specific files/directories
basedpyright src/ tests/

# Watch mode for development
basedpyright --watch

# Output JSON for tooling integration
basedpyright --outputjson

# Verbose diagnostics
basedpyright --verbose

Configuration

Minimal Strict Configuration (pyproject.toml)

[tool.basedpyright]
typeCheckingMode = "strict"
pythonVersion = "3.12"
include = ["src"]
exclude = ["**/__pycache__", "**/.venv"]

# Basedpyright-specific strict rules
reportUnusedCallResult = "error"
reportImplicitStringConcatenation = "error"
reportMissingSuperCall = "error"
reportUninitializedInstanceVariable = "error"

Type Checking Modes

Mode	Description	Use Case
off	No type checking	Legacy code, migration start
basic	Basic type checking	Gradual typing adoption
standard	Standard strictness	Most projects (default Pyright)
strict	Strict type checking	Type-safe codebases
all	Maximum strictness	High-assurance systems

Progressive Type Checking

# Start with basic mode
[tool.basedpyright]
typeCheckingMode = "basic"
include = ["src/new_module"]  # Type check new code only

# Gradually expand
include = ["src/new_module", "src/api"]

# Eventually enable strict mode
typeCheckingMode = "strict"
include = ["src"]

Choosing a Type Checker

Factor	Basedpyright	Pyright	mypy
Speed	Fastest	Fastest	Slower
Strictness	Strictest defaults	Configurable	Configurable
LSP Support	Built-in	Built-in	Via dmypy
Plugin System	Limited	Limited	Extensive

Choose Basedpyright for maximum type safety with stricter defaults and fastest speed. Choose Pyright for Microsoft's official support and VS Code Pylance compatibility. Choose mypy for extensive plugin ecosystem (django-stubs, pydantic-mypy).

Inline Error Suppression

# Inline type ignore
result = unsafe_operation()  # type: ignore[reportUnknownVariableType]

# Function-level ignore
def legacy_function():  # basedpyright: ignore
    pass

Agentic Optimizations

Context	Command
Quick check	basedpyright
JSON output	basedpyright --outputjson
Watch mode	basedpyright --watch
CI check	uv run basedpyright
Verbose	basedpyright --verbose

Quick Reference

Flag	Description
--watch	Watch mode for development
--outputjson	JSON output for tooling
--verbose	Verbose diagnostics
--pythonversion X.Y	Override Python version
--level <mode>	Override type checking mode

For detailed configuration options, LSP integration, migration guides, CI setup, and best practices, see REFERENCE.md.