---
id: circular-dict
version: "1.9"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# circular-dict — CircularDict is a high-performance Python data structure that blends the functionality of dictionaries and circular buffers. Inheriting the usage of traditional dictionaries, it allows you to define constraints on size and memory usage. This way, the CircularDict will be always up-to-date with the last N added elements, ensuring that neither the maximum length nor the memory usage limit is exceeded. It is ideal for caching large data structures while maintaining control over memory footprint.

License: permissive · Maintenance: dormant · Downloads: 2.1M/mo

## What it is and what it does

CircularDict wraps Python's OrderedDict to create a self-managing cache that enforces size limits. You can constrain it by maximum item count (maxlen), total memory footprint in bytes (maxsize_bytes), or both. When a new entry would exceed the limit, the oldest items are automatically removed to make room, keeping memory usage predictable.

It behaves like a standard Python dictionary in all other respects—you use it with normal dict syntax (subscript access, iteration, keys/values/items methods). The main use case is building bounded caches where you want the most recent items or a fixed memory budget without manually evicting old entries. If you try to add a single item larger than maxsize_bytes, it raises MemoryError rather than silently failing.

Use it for:

- Build a time-series cache that keeps only recent measurements without manual cleanup.
- Implement a bounded cache for expensive computations with a fixed memory budget.
- Store recent log entries or events in memory while preventing unbounded growth.
- Cache numpy arrays or large objects with a strict byte-size limit to avoid memory leaks.
- Maintain a fixed-size buffer of recent API responses or database query results.

## Worth the install?

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

CircularDict is a Python dictionary that automatically removes oldest entries when it reaches a size limit (by item count or total bytes), acting as a bounded circular buffer for memory-controlled caching and data storage.

Yes, if you need a simple, zero-dependency bounded cache. The package is stable (Production/Stable classifier, no known vulnerabilities), installs cleanly, and solves a real problem. The dormant maintenance status is not a concern for a narrow, well-defined utility—there is little reason to change it. Use it when you want automatic FIFO eviction with either item-count or memory-size limits; avoid it if you need LRU semantics (evict least recently used, not oldest) or active development support.

## Install

pip install circular-dict
uv add circular-dict
poetry add circular-dict

## Installing circular-dict

Before you install: No runtime dependencies and a pure-Python wheel distribution make installation straightforward. The package is dormant (last commit 2024-05-13, 824 days since first release), so expect no active maintenance, though the codebase appears stable.

License in practice: MIT license is permissive, allowing use in commercial and private projects with minimal restrictions—only requiring attribution and inclusion of the license text.

Quickstart:

pip install circular-dict

from circular_dict import CircularDict

# Create a dict limited to 3 items
my_dict = CircularDict(maxlen=3)
my_dict['a'] = 1
my_dict['b'] = 2
my_dict['c'] = 3
my_dict['d'] = 4  # Oldest entry ('a') is removed automatically

Requires Python 3.6 or later; no other system dependencies.

Verify before relying:

- Performance characteristics (insertion/deletion speed) compared to standard dict or other circular buffer implementations.
- Behavior and accuracy of memory size calculation when storing complex nested objects or numpy arrays.
- Thread safety guarantees, if any, for concurrent access patterns.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 2.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

circular buffer dictionary, bounded cache data structure, memory-limited dict, auto-evicting dictionary, fixed-size circular queue, LRU-like dictionary, memory-capped dict, caching, circular-buffer, memory-management

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