---
id: sortedcontainers-stubs
version: "2.4.3"
license: Apache-2.0
license_treatment: permissive
maintenance: aging
---

# sortedcontainers-stubs — Type stubs for sortedcontainers

License: permissive · Maintenance: aging · Downloads: 1.1M/mo

## What it is and what it does

sortedcontainers-stubs is a type stub package that teaches type checkers like mypy about the sortedcontainers library's API. The sortedcontainers library provides ordered dict, set, and list data structures that maintain elements sorted by value rather than insertion order, and these types have different requirements and methods than Python's built-in equivalents. Without type stubs, type checkers cannot validate that you're using these types correctly.

The package is maintained separately from sortedcontainers itself because the main library's author chose not to include type annotations in the core codebase. The stubs handle the library's API quirks, including the distinction between regular and key-function variants of SortedDict and SortedSet (which are stub-only types) and SortedKeyList (which exists at runtime). Version numbers track sortedcontainers releases: version 2.4.3 of the stubs supports sortedcontainers 2.x.

Use it for:

- Enable mypy or other type checkers to catch incorrect usage of SortedDict, SortedSet, or SortedList in your codebase.
- Get IDE autocomplete and type hints for sortedcontainers methods and their return types.
- Validate that keys or values passed to sorted containers meet their comparability or hashability requirements at type-check time.
- Distinguish between SortedDict and SortedKeyDict in type annotations to document whether a key function is used.
- Maintain type safety in projects that rely on sortedcontainers for performance-critical sorted data structures.

## Worth the install?

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

Provides type stubs for the sortedcontainers library, enabling type checkers like mypy to validate code using SortedDict, SortedSet, and SortedList with their specific API requirements.

Yes, if you use sortedcontainers and run mypy or another type checker. The package is low-friction to install, has no known vulnerabilities, and is actively maintained. The aging status reflects infrequent releases rather than abandonment—the repo is not archived and received a commit in April 2025. Install it alongside sortedcontainers to get full type coverage.

## Install

pip install sortedcontainers-stubs
uv add sortedcontainers-stubs
poetry add sortedcontainers-stubs

## Installing sortedcontainers-stubs

Before you install: Low friction install as a pure stub package with only sortedcontainers and typing-extensions as runtime dependencies. Last commit was recent (2025-04-23), though the package shows aging maintenance status with 478 days since the last release.

License in practice: Apache-2.0 is permissive; you can use this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install sortedcontainers-stubs

import sortedcontainers
sd: sortedcontainers.SortedDict = sortedcontainers.SortedDict()

Requires Python 3.9 or later; sortedcontainers must also be installed as a runtime dependency.

Verify before relying:

- Whether type stub coverage is complete for all sortedcontainers 2.4.x APIs and edge cases.
- Whether the stubs correctly distinguish between stub-only types (SortedKeyDict, SortedKeySet) and runtime types (SortedKeyList) in all type-checking scenarios.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 1.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

type stubs sortedcontainers, mypy sortedcontainers types, sorteddict type checking, sortedset type hints, sortedlist type stubs, python type stubs, sortedcontainers typing, type-stubs, type-checking

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