scipy-stubs

Precise type hints for all of SciPy.

Python Versions
license
PyPI Downloads

typed

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:

Examples

Prevent mistakes with precise type hints:

Accurate annotations for dtypes and shapes:

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.

Note that not all classes are subscriptable at runtime, as that requires the __class_getitem__ method to be implemented in scipy.
This can be worked around with from __future__ import annotations or by manually stringifying the generic annotations.
We are working on improving this in future versions of SciPy.
See the scipy columns below for which classes are subscriptable at runtime.

`scipy.integrate`

generic type	`scipy-stubs`	`scipy`
`BDF[T: f64 \| c128]`	`>=1.14.0.1`	`>=1.17`	docs
`DOP853[T: f64 \| c128]`	`>=1.14.0.1`	`>=1.17`	docs
`RK23[T: f64 \| c128]`	`>=1.14.0.1`	`>=1.17`	docs
`RK45[T: f64 \| c128]`	`>=1.14.0.1`	`>=1.17`	docs
`ode[*ArgTs]`	`>=1.14.0.0`	`>=1.17`	docs
`complex_ode[*ArgTs]`	`>=1.14.0.0`	`>=1.17`	docs

`scipy.interpolate`

generic type	`scipy-stubs`	`scipy`
`AAA[T: inexact]`	`>=1.15.0.0`	`>=1.17`	docs
`BarycentricInterpolator[T: f64 \| c128]`	`>=1.16.0.1`	`>=1.17`	docs
`BPoly[T: f64 \| c128]`	`>=1.14.1.4`	`>=1.17`	docs
`BSpline[T: f64 \| c128]`	`>=1.14.1.6`	`>=1.17`	docs
`CubicHermiteSpline[T: f64 \| c128]`	`>=1.14.1.4`	`>=1.17`	docs
`CubicSpline[T: f64 \| c128]`	`>=1.14.1.4`	`>=1.17`	docs
`FloaterHormannInterpolator[T: f64 \| c128]`	`>=1.15.0.0`	`>=1.17`	docs
`KroghInterpolator[T: f64 \| c128, S: (int, ...)]`	`>=1.16.0.1`	`>=1.17`	docs
`LinearNDInterpolator[T: f64 \| c128]`	`>=1.15.0.0`	`>=1.17`	docs
`NdBSpline[T: f64 \| c128]`	`>=1.15.2.1`	`>=1.17`	docs
`NdPPoly[T: f64 \| c128]`	`>=1.14.1.4`	`>=1.17`	docs
`NearestNDInterpolator[T: f64 \| c128]`	`>=1.14.1.6`	`>=1.17`	docs
`PPoly[T: f64 \| c128]`	`>=1.14.1.4`	`>=1.17`	docs
`RBFInterpolator[T: f64 \| c128, S: (int, ...)]`	`>=1.16.0.1`	`>=1.17`	docs
`RegularGridInterpolator[T: f64 \| c128]`	`>=1.14.1.6`	`>=1.17`	docs

`scipy.optimize`

generic type	`scipy-stubs`	`scipy`
`BroydenFirst[T: inexact]`	`>=1.15.2.0`	`>=1.17`	docs
`InverseJacobian[T: inexact]`	`>=1.15.2.0`	`>=1.17`	docs
`KrylovJacobian[T: inexact]`	`>=1.15.2.0`	`>=1.17`	docs
`Bounds[S: (int, int, ...), T: scalar]`	`>=1.16.0.1`	`>=1.17`	docs

`scipy.signal`

generic type	`scipy-stubs`	`scipy`
`ShortTimeFFT[T: inexact]`	`>=1.16.0.0`	`>=1.17`	docs
`StateSpace[Z: inexact, P: floating, D: scalar]`	`>=1.15.2.0`	`>=1.17`	docs
`TransferFunction[P: floating, D: scalar]`	`>=1.15.2.0`	`>=1.17`	docs
`ZerosPolesGain[Z: inexact, P: floating, D: scalar]`	`>=1.15.2.0`	`>=1.17`	docs
`lti[Z: inexact, P: floating]`	`>=1.15.2.0`	`>=1.17`	docs
`dlti[Z: inexact, P: floating, D: scalar]`	`>=1.15.2.0`	`>=1.17`	docs

`scipy.sparse`

generic type	`scipy-stubs`	`scipy`
`bsr_array[T: scalar]`	`>=1.14.1.6`	`>=1.16`	docs
`bsr_matrix[T: scalar]`	`>=1.14.1.6`	`>=1.16`	docs
`coo_array[T: scalar, S: (int, ...)]`	`>=1.14.1.6`	`>=1.16`	docs
`coo_matrix[T: scalar]`	`>=1.14.1.6`	`>=1.16`	docs
`csc_array[T: scalar]`	`>=1.14.1.6`	`>=1.16`	docs
`csc_matrix[T: scalar]`	`>=1.14.1.6`	`>=1.16`	docs
`csr_array[T: scalar, S: (int,) \| (int, int)]`	`>=1.14.1.6`	`>=1.16`	docs
`csr_matrix[T: scalar]`	`>=1.14.1.6`	`>=1.16`	docs
`dia_array[T: scalar]`	`>=1.14.1.6`	`>=1.16`	docs
`dia_matrix[T: scalar]`	`>=1.14.1.6`	`>=1.16`	docs
`dok_array[T: scalar, S: (int,) \| (int, int)]`	`>=1.14.1.6`	`>=1.16`	docs
`dok_matrix[T: scalar]`	`>=1.14.1.6`	`>=1.16`	docs
`lil_array[T: scalar]`	`>=1.14.1.6`	`>=1.16`	docs
`lil_matrix[T: scalar]`	`>=1.14.1.6`	`>=1.16`	docs
`sparray[T: scalar, S: (int, ...)]`	`>=1.15.2.0`	`>=1.16`	docs
`spmatrix[T: scalar]`	`>=1.14.1.6`	`>=1.16`	docs

`scipy.sparse.linalg`

generic type	`scipy-stubs`	`scipy`
`LaplacianNd[T: real]`	`>=1.14.1.6`	`>=1.17`	docs
`LinearOperator[T: scalar]`	`>=1.14.1.6`	`>=1.17`	docs
`SuperLU[T: inexact]`	`>=1.16.0.1`	`>=1.17`	docs

`scipy.stats`

generic type	`scipy-stubs`	`scipy`
`Covariance[T: real]`	`>=1.14.0.0`	`>=1.17`	docs
`Uniform[S: (int, ...), T: floating]`	`>=1.15.0.0`	`>=1.17`	docs
`Normal[S: (int, ...), T: floating]`	`>=1.15.0.0`	`>=1.17`	docs
`Binomial[S: (int, ...), T: floating]`	`>=1.16.0.0`	`>=1.17`	docs
`Mixture[T: floating]`	`>=1.15.0.0`	`>=1.17`	docs
`rv_frozen[D: rv_generic, T: scalar or array]`	`>=1.14.0.0`	`>=1.17`
`multi_rv_frozen[D: rv_generic]`	`>=1.14.0.0`	`>=1.17`

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.

Dependencies of scipy-stubs (2).
Dependency	Optional
optype	false
scipy	true

Package profile

scipy-stubs

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description