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.