scipy-stubs

Precise type hints for all of SciPy.

Quick Start

Install scipy-stubs and start getting better type hints immediately:

pip install scipy-stubs

That's it! Your IDE and type checker will now provide precise type information for SciPy functions:

Why use scipy-stubs?

Enhanced Development Experience

• Better IDE support: Get accurate autocompletion, parameter hints, and return type information
• Catch errors early: Type checkers can detect mistakes before runtime
• Improved code documentation: Type hints serve as inline documentation for function signatures

Zero Configuration Required

• Drop-in replacement: Works immediately after installation, no configuration needed
• No runtime impact: Type stubs are only used during development and type checking
• IDE agnostic: Works with VSCode, PyCharm, Vim, Emacs, and any editor with Python language server support

Precise and Complete

• Array shape awareness: Many functions include shape-type information for better array handling
• Generic types: Supports generic types for sparse arrays, distributions, and more
• Complete coverage: Type hints are provided for the entire SciPy API

Installation

The source code is hosted on GitHub at github.com/scipy/scipy-stubs.

Binary distributions are available on PyPI and conda-forge.

Using pip (PyPI)

To install from the PyPI, run:

pip install scipy-stubs

In case you haven't installed scipy yet, both can be installed with:

pip install scipy-stubs[scipy]

Using conda (conda-forge)

To install using Conda from the conda-forge channel, run:

conda install conda-forge::scipy-stubs

It's also possible to install both scipy and scipy-stubs together through the bundled scipy-typed package:

conda install conda-forge::scipy-typed

Frequently Asked Questions

Q: Do I need to change my existing code?

A: No! scipy-stubs works with your existing code without any modifications. Just install it and your type checker and IDE will automatically use the type information.

Q: Will this slow down my code?

A: Not at all. Type stubs are only used during development and type checking. They have zero runtime overhead since they're not imported when your code runs.

Q: What if I don't use type hints in my code?

A: You'll still benefit! Your IDE will provide better autocompletion and error detection even without explicit type annotations in your code.

Q: Can I use this with Jupyter notebooks?

A: Yes! Most modern Jupyter environments (JupyterLab, VS Code notebooks) support type checking and will benefit from scipy-stubs.

Q: What's the difference between this and the built-in scipy typing?

A: SciPy itself has limited type annotations. scipy-stubs provides comprehensive, precise type information for the entire SciPy API, including shape-typing and advanced type features.

Q: How do I know if it's working?

A: You should see improved autocompletion in your IDE and more precise type information. You can also run pyright or another type checker on your code to see type checking in action.

Q: How much of SciPy is covered?

A: All of it! If you find any missing or incorrect type annotations, please open an issue on GitHub.

Q: What static type-checkers are supported?

A: scipy-stubs is compatible with pyright (a.k.a. pylance), basedpyright, and mypy. We only support the latest versions of these type-checkers, so make sure to keep them up to date.

Versioning and requirements

The versioning scheme of scipy-stubs includes the compatible scipy version as {scipy_version}.{stubs_version}. Even though scipy-stubs doesn't enforce an upper bound on the scipy version, later scipy versions aren't guaranteed to be fully compatible.

There are no additional restrictions enforced by scipy-stubs on the numpy requirements. For scipy-stubs==1.16.* that is numpy >= 1.25.2.

Currently, scipy-stubs has one required dependency: optype. This is essential for scipy-stubs to work properly, as it relies heavily on it for annotating (shaped) array-likes, scalar-likes, shape-typing in general, and much more. At the moment, scipy-stubs requires the latest version optype.

The exact version requirements are specified in the pyproject.toml.

Contributing

We welcome contributions from the community! There are many ways to help improve scipy-stubs:

Ways to Contribute

• Report issues: Found a bug or incorrect type annotation? Open an issue
• Improve stubs: Fix or enhance .pyi files (see CONTRIBUTING.md)
• Add tests: Help with type-testing (see the README.md in tests/)
• Documentation: Write guides, examples, or improve existing documentation
• Spread the word: Help others discover scipy-stubs

Development Setup

See the CONTRIBUTING.md for detailed instructions.

License

scipy-stubs is licensed under the BSD 3-Clause License, the same as SciPy itself.