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: Comprehensive generic classes for sparse arrays, distributions, linear operators, 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.

Generics

scipy-stubs provides many generic classes that enable precise type checking for SciPy's complex APIs.

All generic type parameters are optional and can be omitted if not needed.

scipy.integrate

generic type
BDF[T: float64 | complex128]	docs
DOP853[T: float64 | complex128]	docs
RK23[T: float64 | complex128]	docs
RK45[T: float64 | complex128]	docs
ode[*ArgTs]	docs
complex_ode[*ArgTs]	docs

scipy.interpolate

generic type
AAA[T: inexact]	docs
BarycentricInterpolator[T: float64 | complex128]	docs
BPoly[T: float64 | complex128]	docs
BSpline[T: float64 | complex128]	docs
CubicHermiteSpline[T: float64 | complex128]	docs
CubicSpline[T: float64 | complex128]	docs
FloaterHormannInterpolator[T: float64 | complex128]	docs
KroghInterpolator[T: float64 | complex128]	docs
LinearNDInterpolator[T: float64 | complex128]	docs
NdBSpline[T: float64 | complex128]	docs
NdPPoly[T: float64 | complex128]	docs
NearestNDInterpolator[T: float64 | complex128]	docs
PPoly[T: float64 | complex128]	docs
RBFInterpolator[S: (int, ...), T: float64 | complex128]	docs
RegularGridInterpolator[T: float64 | complex128]	docs

scipy.optimize

generic type
BroydenFirst[T: inexact]	docs
InverseJacobian[T: inexact]	docs
KrylovJacobian[T: inexact]	docs
Bounds[S: (int, int, ...), T: scalar]	docs

scipy.signal

generic type
ShortTimeFFT[T: inexact]	docs
StateSpace[Z: inexact, P: floating, D: scalar]	docs
TransferFunction[P: floating, D: scalar]	docs
ZerosPolesGain[Z: inexact, P: floating, D: scalar]	docs
lti[Z: inexact, P: floating]	docs
dlti[Z: inexact, P: floating, D: scalar]	docs

scipy.sparse

generic type
bsr_array[T: scalar]	docs
bsr_matrix[T: scalar]	docs
coo_array[T: scalar, S: (int, ...)]	docs
coo_matrix[T: scalar]	docs
csc_array[T: scalar]	docs
csc_matrix[T: scalar]	docs
csr_array[T: scalar, S: (int,) | (int, int)]	docs
csr_matrix[T: scalar]	docs
dia_array[T: scalar]	docs
dia_matrix[T: scalar]	docs
dok_array[T: scalar, S: (int,) | (int, int)]	docs
dok_matrix[T: scalar]	docs
lil_array[T: scalar]	docs
lil_matrix[T: scalar]	docs
sparray[T: scalar, S: (int, ...)]	docs
spmatrix[T: scalar]	docs

scipy.sparse.linalg

generic type
LaplacianNd[T: real]	docs
LinearOperator[T: scalar]	docs
SuperLU[T: inexact]	docs

scipy.stats

generic type
Covariance[T: real]	docs
Uniform[S: (int, ...), T: floating]	docs
Normal[S: (int, ...), T: floating]	docs
Binomial[S: (int, ...), T: floating]	docs
Mixture[T: floating]	docs
rv_frozen[D: rv_generic, T: scalar or array]
multi_rv_frozen[D: rv_generic]

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.