Reasons not to use pyright
While Pyright, particularly its integration via Pylance in VS Code, offers superior speed and a responsive developer experience, it is not without its drawbacks. For certain projects, teams, or development philosophies, Pyright's characteristics can lead to friction, complexity, or outright incompatibility.
Here is a critical assessment of the reasons why an experienced developer might choose not to rely on Pyright, or use it only in a secondary role.
1. Philosophical Deviation from CPython Standards (PEPs)
Pyright is implemented by Microsoft and maintains a philosophy focused on making the developer experience (DX) excellent. While it follows Python Enhancement Proposals (PEPs), its interpretation or implementation of newer or edge-case typing features can sometimes differ from MyPy, which often serves as the reference implementation.
- Risk of False Negatives (Over-Forgiveness): Pyright is generally considered more "forgiving" than MyPy. This speed comes partly from making more optimistic type inferences. This can lead to a false sense of security where Pyright passes code that MyPy (the stricter, PEP-aligned checker) would reject, potentially masking subtle runtime bugs.
- Non-Standard Behavior: In some advanced scenarios (e.g., complex structural typing, non-standard metaclasses), Pyright might implement a feature based on its own effective structural analysis rather than the exact PEP specification, making the code harder to reason about if you are only familiar with the PEPs.
2. Lack of Custom Plugin Ecosystem
MyPy's greatest long-term advantage is its robust plugin system. This allows large, specialized Python libraries to teach MyPy how to understand their dynamic, type-unfriendly code generation patterns.
- Incompatibility with Dynamic Libraries: Libraries that rely on runtime reflection or code generation (e.g., SQLAlchemy's ORM, certain dataclass libraries, specific web frameworks) often ship with MyPy plugins to ensure their code is properly type-checked.
- The Problem: Pyright lacks an equivalent public plugin API. This means that if you rely heavily on an ORM like SQLAlchemy, Pyright will often throw numerous (and often incorrect) type errors or fail to infer types correctly, forcing you to use many more
# type: ignorecomments than MyPy would require.
3. Tightly Coupled VS Code / Pylance Integration
Pyright's performance is optimized for the Language Server Protocol (LSP), making it the engine behind Pylance in VS Code. This deep integration is a double-edged sword:
- Tooling Lock-in: Teams that primarily use other IDEs (like PyCharm, which uses its own highly effective internal type checker) or simpler editors cannot easily leverage Pyright's speed or features without adopting VS Code.
- Configuration Drift: It can be difficult to ensure that the settings used by the local Pylance/Pyright instance perfectly match the settings used in a command-line CI environment, leading to "works on my machine" type errors.
4. Implementation Language Dependency
Pyright is written in TypeScript and typically runs using Node.js.
- Dependency on Node.js: While this allows Pyright to be extremely fast, it introduces a foreign language runtime dependency for a pure Python project. This adds overhead and complexity to CI environments that are otherwise pure Python/pip builds.
- Contribution Barrier: For developers who want to contribute bug fixes or new features, they must be proficient in TypeScript, which is an unnecessary barrier compared to contributing to MyPy (which is written in Python).
Summary of Drawbacks and Strategic Advice
| Drawback | Impact | Strategic Advice |
|---|---|---|
| Philosophical Drift | Potential for false negatives; masking subtle bugs. | Use MyPy as the CI gatekeeper to ensure maximum PEP compliance. |
| No Plugin System | Incorrect typing for dynamic libraries (e.g., SQLAlchemy, advanced metaclasses). | If using highly dynamic libraries, MyPy is mandatory for reliable checking. |
| IDE Lock-in | Inconvenient for developers not using VS Code. | Standardize on MyPy for project-wide consistency and CI. |
| Node.js Dependency | Adds a non-Python runtime dependency to the build/CI environment. | Weigh the speed gain against the complexity of adding Node.js to your stack. |
The Expert Conclusion: Pyright is an indispensable developer experience tool, but it should rarely be relied upon as the sole authority for type checking in a large, complex, or multi-IDE Python project. A dual-tool strategy (Pyright locally, MyPy in CI) is often the most robust solution.