---
id: numpy-typing-compat
version: "20260602.2.5"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# numpy-typing-compat — Static typing compatibility layer for older versions of NumPy

License: permissive · Maintenance: active · Downloads: 3.9M/mo

## What it is and what it does

numpy-typing-compat is a compatibility layer that lets you write NumPy type annotations that adapt to the installed NumPy version. It provides version-specific boolean constants (like NUMPY_GE_2_1) and type aliases (StringDType, ABCPolyBase, LiteralTrue, LiteralFalse) that static type-checkers can understand, similar to how you'd use sys.version_info for Python version checks. This is particularly useful for library authors who need to support multiple NumPy versions while maintaining accurate type hints.

The package is tightly coupled to NumPy versions—each release targets a specific NumPy minor version range (e.g., 20260602.2.5 targets numpy >=2.4,<2.5). Modern package managers like uv and pixi automatically install the correct version, but pip users must manually ensure alignment. The package is actively maintained and designed as a helper for the optype library, though it can be used directly when you need fine-grained version-aware typing.

Use it for:

- Library authors supporting multiple NumPy versions who need type-checkers to understand version-specific APIs without runtime overhead
- Conditional type annotations for NumPy 2.0+ features like StringDType that weren't available in earlier versions
- Handling NumPy 2.1+ generic type changes (ABCPolyBase) while maintaining backward compatibility with older versions
- Type-safe use of NumPy 2.2+ bool scalar generics (LiteralTrue, LiteralFalse) across version boundaries

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides version-specific type annotations for NumPy code, allowing static type-checkers to understand which NumPy version is installed and apply appropriate type hints accordingly.

Yes, if you are a library author supporting multiple NumPy versions and need static type-checkers to understand version-specific type differences. Use modern package managers (uv, pixi) to avoid manual version management. Not necessary for applications using a single NumPy version or if you rely on optype for higher-level typing utilities.

## Install

pip install numpy-typing-compat
uv add numpy-typing-compat
poetry add numpy-typing-compat

## Installing numpy-typing-compat

Before you install: Low install friction with a single runtime dependency on numpy. Actively maintained as of 2026-08-14 with recent releases. Requires Python 3.12 or later and is designed to work with modern package managers like uv and pixi that respect version constraints; pip users must manually ensure version compatibility.

License in practice: BSD-3-Clause permissive license allows use in most projects without significant restrictions.

Quickstart:

pip install numpy-typing-compat

from numpy_typing_compat import NUMPY_GE_2_1, StringDType

if NUMPY_GE_2_1:
    dtype = StringDType()
else:
    dtype = None

Requires Python 3.12 or later. The installed version of numpy-typing-compat must match your NumPy version—modern package managers handle this automatically, but pip requires manual version alignment.

Verify before relying:

- How well mypy and pyright actually support Literal-based version conditions in practice beyond the documented 'limited support'
- Whether the package is actively used by optype or other production libraries beyond its intended helper role

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 3.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

numpy version-specific type annotations, numpy typing compatibility layer, conditional numpy type hints, numpy static type checking, numpy version detection typing, numpy dtype type stubs, numpy 2.x typing support, numpy-typing, type-checking, version-compat

[View on SkillFed](https://skillfed.io/packages/numpy-typing-compat) · [View on PyPI](https://pypi.org/project/numpy-typing-compat/)