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.
