• Repository

Meta

• Author: Joren Hammudoglu
• Maintainer: Joren Hammudoglu, SciPy Developers

Meta

• License Expression: BSD-3-Clause
  SPDX License Expression
• Author: Joren Hammudoglu
• Maintainer: Joren Hammudoglu, SciPy Developers
• Tags scipy , typing , stubs , mypy , pyright , pep484 , pep561 , scipy-stubs
• Requires: Python >=3.12
• Provides-Extra: scipy

Classifiers

• Development Status
  • 5 - Production/Stable
• Intended Audience
  • Developers
  • Science/Research
• Operating System
  • OS Independent
• Programming Language
  • Python
  • Python :: 3
  • Python :: 3.12
  • Python :: 3.13
  • Python :: 3.14
• Typing
  • Stubs Only

scipy-stubs

The official type stubs for SciPy.

👁 GitHub License
👁 PyPI Version
👁 Conda Version
👁 Python Versions
👁 PyPI Downloads

Used by Pandas, JAX, Apache Spark, Astropy, Ultralytics, Altair, and many other projects.

Features

• Complete coverage: the entire public SciPy API is annotated.
• Shape- and dtype-aware: array shapes and dtypes are tracked where applicable.
• Generics: subscriptable types for sparse arrays, distributions, splines, and linear operators.
• No configuration: works on install, affects type checking only, with no runtime impact.
• Broad checker support: tested against mypy, pyright, basedpyright, pyrefly, and ty.
• Thoroughly tested: stubtest against the runtime, assert_type tests for inference, and mypy_primer for regressions.

Examples

Accurate type hints for shapes and dtypes

Prevent mistakes with precise type hints

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:

pipinstallscipy-stubs

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

pipinstallscipy-stubs[scipy]

Using conda (conda-forge)

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

condainstallconda-forge::scipy-stubs

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

condainstallconda-forge::scipy-typed

Why is scipy-stubs a separate package?

Here are some of the key reasons why scipy-stubs is maintained as a separate package rather than being integrated into SciPy itself.

Separation of concerns

If scipy-stubs were part of SciPy, every contributor would need to be familiar with type stubs. Some areas of scipy-stubs get intricate, so keeping them in good shape goes more smoothly when you’re comfortable with how the typing pieces interact (example). Requiring all SciPy developers to become typing experts would likely reduce overall willingness to contribute. By keeping stubs separate, SciPy contributors can focus on scientific functionality while typing specialists handle the stubs, with each group reviewing changes in its domain of expertise.

Opt-in by design

A significant portion of SciPy users don’t use type checking. Without scipy-stubs installed, type checkers won’t analyze SciPy-related code. Some patterns may be technically type-unsafe while still working fine in practice, and installing scipy-stubs would flag these cases. By keeping stubs separate, users retain full control over whether to enable type checking for their SciPy code.

Independent release cycles

The scipy-stubs versioning scheme uses four numbers: {scipy_version}.{stubs_version}. The first three match the SciPy semver version, while the fourth is specific to stub releases. Since stub releases occur more frequently than SciPy releases, this independence allows typing improvements and bug fixes to ship without waiting for the next SciPy version.

CI efficiency

The SciPy CI pipeline is large and takes over 30 minutes to run. The scipy-stubs CI is lightweight and finishes in under 4 minutes. This difference has a real impact on development workflow, enabling quicker iteration and faster delivery of changes. The speed gap exists mainly because scipy-stubs doesn’t require compilation - it can rely on SciPy’s pre-built wheels.

Frequently Asked Questions

Q: What static type-checkers are supported?

A: scipy-stubs is tested against the most recent stable versions of

• Mypy,
• Pyright (a.k.a. Pylance),
• BasedPyright,
• Pyrefly, and
• ty (currently in beta, so it may not always work as expected).

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: 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: Can I use this with Jupyter notebooks?

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

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: 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 mypy, pyright or another type checker on your code to see type checking in action.

Q: Is this vibe-coded?

A: No.

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.18.* that is numpy >= 2.0.0.

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.

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 #1099 and 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.

Who's using scipy-stubs?

scipy-stubs is used by a number of major open-source projects, including:

Agents | Apache Spark (PySpark) | Artisan | Arviz | asammdf | Astropy | Chemotools | Colour (Colour, Checker Detection, Demosaicing, HDRI, Visuals) | CSAPS | cuPyNumeric | derwen.ai (kglab) | Dify | Dify-Plus | Dingo | Efax | Fast GraphRAG | foamlib | Freqtrade | graphix | Gurobi (gurobi-logtools) | JAX | LazySlide | LensKit | librosa | linearmodels | Lmo | Materialize | MaxText | Metta AI (mettagrid) | MolPipeline | Monad | MouseTracks | movement | Mozilla (mozanalysis) | MTEB | mypy_primer | Namer | NeuroGym | Numba | Optuna | pandapower | Pandas (pandas, pandas-stubs) | Pandera | ProgressiVis | ProLIF | Ptera Software | PyMC (PyTensor) | pysmo | python-hvac | radioactivedecay | scikit-fingerprints | scqubits | scverse (PyDESeq2, scanpy) | SeQUeNCe | Skore | Splipy | Theis Lab (anndata2ri) | TorchFX | TQEC | traccuracy | Ultralytics | Vega (Altair) | Voctomix | xarray

License

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

Verified details

These details have been verified by PyPI

Project links

• Changelog
• Issues
• Repository

GitHub Statistics

Maintainers

👁 Avatar for jhammudoglu from gravatar.com
jhammudoglu 👁 Avatar for rgommers from gravatar.com
rgommers

Unverified details

These details have not been verified by PyPI

Project links

• Homepage

• Download URL: scipy_stubs-1.18.0.0.tar.gz
• Upload date: Jun 19, 2026
• Size: 402.5 kB
• Tags: Source
• Uploaded using Trusted Publishing? Yes
• Uploaded via: twine/6.1.0 CPython/3.13.13

Hashes for scipy_stubs-1.18.0.0.tar.gz

Algorithm	Hash digest
SHA256	a1fc917da66e4d338998839170e218754a669f6455c24243890a1e572bde98f6
MD5	99557c918ea09e76c61e218b65abc53b
BLAKE2b-256	e59b6cb11393563241c79b74e035c1d697329d1dce1635565e40b0085d56a2fe

See more details on using hashes here.

• Download URL: scipy_stubs-1.18.0.0-py3-none-any.whl
• Upload date: Jun 19, 2026
• Size: 608.2 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? Yes
• Uploaded via: twine/6.1.0 CPython/3.13.13

Hashes for scipy_stubs-1.18.0.0-py3-none-any.whl

Algorithm	Hash digest
SHA256	872ec1066a75feb5c5d8451231e8f7826d08d53fb806c526abd5f97bb1ba29fb
MD5	48f00a16585e34c091f6b86bb47487d1
BLAKE2b-256	e9b482d4de656500722dea533151b88f926672341b46289cc31eb2e2c1c7c1d7

See more details on using hashes here.