{"id":2763,"library":"scipy-stubs","title":"SciPy Type Stubs","description":"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.","status":"active","version":"1.17.1.3","language":"en","source_language":"en","source_url":"https://github.com/scipy/scipy-stubs","tags":["type stubs","typing","scipy","numpy","scientific computing","static analysis"],"install":[{"cmd":"pip install scipy-stubs","lang":"bash","label":"Standard Installation"},{"cmd":"pip install scipy-stubs[scipy]","lang":"bash","label":"Install with SciPy if not already present"}],"dependencies":[{"reason":"Provides type annotations for this library; must be installed for runtime functionality.","package":"scipy","optional":false},{"reason":"SciPy's core dependency, and scipy-stubs provides typing for its interaction with SciPy.","package":"numpy","optional":false},{"reason":"Required for advanced shape-typing and array-like annotations in the stubs.","package":"optype","optional":false}],"imports":[{"note":"scipy-stubs provides type hints for your regular scipy imports; you do not import scipy-stubs itself.","symbol":"scipy","correct":"import scipy"},{"note":"scipy-stubs provides type hints for your regular scipy imports; you do not import scipy-stubs itself.","symbol":"optimize","correct":"from scipy import optimize"},{"note":"scipy-stubs provides type hints for your regular scipy imports; you do not import scipy-stubs itself.","symbol":"linalg","correct":"from scipy import linalg"}],"quickstart":{"code":"import numpy as np\nfrom scipy.optimize import minimize, OptimizeResult\nfrom typing import Tuple\n\ndef rosen(x: np.ndarray) -> np.float64:\n    \"\"\"The Rosenbrock function\"\"\"\n    return np.sum(100.0 * (x[1:] - x[:-1]**2.0)**2.0 + (1 - x[:-1])**2.0)\n\ndef rosen_der(x: np.ndarray) -> np.ndarray:\n    \"\"\"The Rosenbrock function gradient\"\"\"\n    xm = x[1:-1]\n    xm_m1 = x[:-2]\n    xm_p1 = x[2:]\n    grad = np.zeros_like(x)\n    grad[1:-1] = 200.0 * (xm - xm_m1**2) - 400.0 * (xm_p1 - xm**2) * xm - 2.0 * (1 - xm)\n    grad[0] = -400.0 * x[0] * (x[1] - x[0]**2) - 2.0 * (1 - x[0])\n    grad[-1] = 200.0 * (x[-1] - x[-2]**2)\n    return grad\n\nx0: np.ndarray = np.array([0.5, 0.5])\nres: OptimizeResult = minimize(rosen, x0, method='BFGS', jac=rosen_der, options={'disp': True})\n\nprint(f\"Optimization successful: {res.success}\")\nprint(f\"Function value at minimum: {res.fun}\")\nprint(f\"Optimal parameters: {res.x}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"In `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.","severity":"breaking","affected_versions":">=1.16.3.3"},{"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.","message":"Ensuring 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Type 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Earlier 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).","severity":"gotcha","affected_versions":"<1.17.1.2"},{"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.","message":"Certain 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.","severity":"gotcha","affected_versions":"<1.17.1.1"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}