Registry / type-stubs / scipy-stubs

scipy-stubs

JSON →
library1.18.1.0pypypi✓ verified 24d ago

scipy-stubs provides comprehensive type annotations for the SciPy library, enabling static type checking for SciPy-based projects and enhancing IDE features like autocompletion and error detection. It offers full coverage of the public SciPy API with precise shape-typing and dtype-typing without any runtime overhead. The current version is 1.17.1.3, designed to be compatible with SciPy 1.17.1 and supporting Python 3.11-3.14. Releases are independent but target specific SciPy versions.

pip install scipy-stubs
INSTALL
IMPORT
SIG · SCIPY-STUBS
S
scipy-stubs
type-stubspythonv1.18.1.0
Install
5.4s avg
Import
Disk
121MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.15.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ —
✓ 4.65s
py 3.11
✓ —
✓ 5.55s
py 3.12
✓ —
✓ 5.7s
py 3.13
✓ —
✓ 5.8s
py 3.9
✕ build_error
✕ build_error
121MB installed
● package 121MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

scipy-stubs
import scipy_stubs
import scipy-stubs

This quickstart demonstrates using `scipy.optimize.minimize` with type annotations for inputs and outputs. After installing `scipy-stubs`, your type checker (like MyPy or Pyright) and IDE will automatically provide type-checking and autocompletion for SciPy functions, even without explicit type annotations in your own code. The stubs ensure that the types for `x0`, `res`, and function arguments are correctly understood.

import numpy as np from scipy.optimize import minimize, OptimizeResult from typing import Tuple def rosen(x: np.ndarray) -> np.float64: """The Rosenbrock function""" return np.sum(100.0 * (x[1:] - x[:-1]**2.0)**2.0 + (1 - x[:-1])**2.0) def rosen_der(x: np.ndarray) -> np.ndarray: """The Rosenbrock function gradient""" xm = x[1:-1] xm_m1 = x[:-2] xm_p1 = x[2:] grad = np.zeros_like(x) grad[1:-1] = 200.0 * (xm - xm_m1**2) - 400.0 * (xm_p1 - xm**2) * xm - 2.0 * (1 - xm) grad[0] = -400.0 * x[0] * (x[1] - x[0]**2) - 2.0 * (1 - x[0]) grad[-1] = 200.0 * (x[-1] - x[-2]**2) return grad x0: np.ndarray = np.array([0.5, 0.5]) res: OptimizeResult = minimize(rosen, x0, method='BFGS', jac=rosen_der, options={'disp': True}) print(f"Optimization successful: {res.success}") print(f"Function value at minimum: {res.fun}") print(f"Optimal parameters: {res.x}")
Debug
Known issues
breakingIn `scipy-stubs` v1.16.3.3, the internal `_lib._util._RichResult` class was changed to be a covariant (immutable) type and no longer a subtype of `dict`. Code relying on `_RichResult` behaving like a `dict` at the type level will break.
fix
Avoid treating `_RichResult` as a `dict` at the type level. Access attributes directly or convert to a dict explicitly if dictionary-like behavior is truly needed.
affects: >=1.16.3.3
gotchaEnsuring version compatibility between `scipy-stubs` and `scipy` is crucial. Each `scipy-stubs` release targets a specific `SciPy` version (e.g., `scipy-stubs 1.17.1.3` targets `SciPy 1.17.1`), and also specifies supported Python and NumPy versions. Mismatched versions can lead to incorrect or missing type hints, causing false positives or negatives from type checkers.
fix
Always install `scipy-stubs` and `scipy` versions that are explicitly compatible. Check the `scipy-stubs` release notes or PyPI page for the exact `SciPy`, Python, and NumPy version requirements. Consider using `pip install scipy-stubs[scipy]` to ensure both are installed correctly.
affects: All versions
gotchaType stubs are for static analysis only; they have no runtime impact or overhead. You do not import from `scipy-stubs` in your code. Instead, you import `scipy` as usual, and your type checker (e.g., MyPy, Pyright) automatically discovers and uses the stub files for type checking.
fix
Understand that `scipy-stubs` is a development-time dependency. Do not add `import scipy_stubs` statements to your production code. Ensure your type checker is configured to find installed stub packages.
affects: All versions
gotchaEarlier versions of `scipy-stubs` (and `SciPy`) had known issues with type hints for `scipy.sparse` array/matrix slicing and multi-indexing operations. These were fixed in recent stub releases (e.g., v1.17.1.2, v1.17.1.3).
fix
Update `scipy-stubs` to the latest compatible version with your `SciPy` installation to benefit from the most accurate type hints, especially for `scipy.sparse` operations.
affects: <1.17.1.2
gotchaCertain generic types provided by `scipy-stubs` (e.g., for `Rotation` or `RigidTransform` in `scipy.spatial.transform`) might not be subscriptable at runtime in older SciPy versions. This could require `from __future__ import annotations` or stringifying type annotations to avoid runtime `TypeError` when using generic types directly in type hints.
fix
Utilize `from __future__ import annotations` in your modules. Keep `scipy-stubs` and `scipy` updated to versions that support runtime subscriptability for generic types if you intend to use them.
affects: <1.17.1.1
Upgrade
Version history
1.18.1.0latest on PyPI · released Aug 22, 2026
Audit
Dependencies
scipyrequiredProvides type annotations for this library; must be installed for runtime functionality.
numpyrequiredSciPy's core dependency, and scipy-stubs provides typing for its interaction with SciPy.
optyperequiredRequired for advanced shape-typing and array-like annotations in the stubs.
Agent activity
31 hits · last 30 days
node
26
OpenAI (training)
1
Resources
scipy-stubs — pip install scipy-stubs · libregistry