lru-dict

library1.4.1pypypi✓ verified 24d ago

lru-dict is a fixed-size dictionary-like container that evicts the Least Recently Used (LRU) items once its capacity limit is exceeded. It is implemented in C for performance and memory efficiency. The library is currently at version 1.4.1 and maintains an active release cadence, focusing on Python version compatibility and minor feature enhancements.

serialization data

pip install lru-dict

github ↗package ↗

INSTALL

IMPORT

SIG · LRU-DICT

lru-dict

serializationpythonv1.4.1

Install

1.6s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.1 · 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

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

LRU

✓ from lru import LRU

Initializes an LRU cache, demonstrates item insertion, eviction, access-based reordering, deletion, resizing, and updates. Includes examples of `items()`, `keys()`, `get_size()`, `set_size()`, and `in` operator usage.

from lru import LRU l = LRU(5) # Create an LRU container with a capacity of 5 for i in range(5): l[i] = str(i) print(f"Initial LRU state: {l.items()}") # Expected: [(4, '4'), (3, '3'), (2, '2'), (1, '1'), (0, '0')] l[5] = '5' # Add a new item, '0' (LRU) should be evicted print(f"After adding 5: {l.items()}") # Expected: [(5, '5'), (4, '4'), (3, '3'), (2, '2'), (1, '1')] l[3] # Accessing an item makes it Most Recently Used (MRU) print(f"After accessing 3: {l.items()}") # Expected: [(3, '3'), (5, '5'), (4, '4'), (2, '2'), (1, '1')] del l[4] # Delete an item print(f"After deleting 4: {l.items()}") # Expected: [(3, '3'), (5, '5'), (2, '2'), (1, '1')] l.set_size(3) # Resize the LRU cache print(f"After resizing to 3: {l.items()}") # Expected: [(3, '3'), (5, '2'), (2, '1')] (order depends on eviction policy details for resize) print(f"Current size: {l.get_size()}") # Get current capacity print(f"Has key 5: {5 in l}") l.update({1: 'one_updated'}) # Update an existing item print(f"After updating 1: {l.items()}")

Debug

Known issues

breakingOlder versions of `lru-dict` (e.g., 1.1.8 and earlier) did not support newer Python versions like 3.11+. Upgrading to `lru-dict >=1.4.0` is required for Python 3.11+ compatibility.

fix

Upgrade to `lru-dict` version 1.4.0 or newer: `pip install --upgrade lru-dict`.

affects: <1.4.0

gotcha`lru-dict` is a C-implemented cache and is explicitly noted as not being thread-safe in older documentation. While not always explicitly stated in newer versions, C extensions often require explicit synchronization for thread-safe operations if not designed for it. Use with caution in multi-threaded environments or implement external locking.

fix

Implement external locking mechanisms (e.g., `threading.Lock`) around `lru-dict` operations when used in concurrent contexts.

affects: All versions

gotcha`lru-dict` provides a dictionary-like container, distinct from `functools.lru_cache`, which is a function decorator for memoization. Users expecting automatic function result caching should use `functools.lru_cache` instead, or wrap `lru-dict` in a custom caching decorator.

fix

Understand the distinction: `lru-dict` manages a collection of items, `functools.lru_cache` memoizes function calls. Choose the appropriate tool for your caching need.

affects: All versions

gotchaLike standard Python dictionaries, `lru-dict` keys must be hashable. Using mutable objects (e.g., lists, dictionaries) as keys will result in a `TypeError`. Modifying a mutable key after insertion can lead to incorrect cache behavior.

fix

Ensure that all keys used with `lru-dict` are immutable (e.g., strings, numbers, tuples). If mutable state is necessary, use a hashable representation of that state as the key.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'lru'

The `lru-dict` library is installed, but the user is attempting to import a module named 'lru' or 'lru_dict' incorrectly; the main class is `LRU` from the `lru` module.

fix

The correct import statement is `from lru import LRU`.

fatal error: Python.h: No such file or directory

`lru-dict` is a C extension that requires Python development headers (e.g., `python3-dev` or `python-devel`) to be present on the system for successful compilation during installation.

fix

Install the appropriate Python development package for your operating system (e.g., `sudo apt-get install python3-dev` on Debian/Ubuntu, `sudo yum install python3-devel` on RHEL/CentOS).

AttributeError: module 'lru' has no attribute 'LRU'

This error typically occurs when a different, possibly incompatible, `lru` module is imported or if `lru-dict` was not installed correctly, leading to the `lru` module not exposing the `LRU` class as expected.

fix

Ensure `lru-dict` is correctly installed (`pip install lru-dict`) and that there are no conflicting `lru` packages. Verify the import `from lru import LRU`. If a conflicting package is present, uninstall it first.

Upgrade

Version history

1.4.1latest on PyPI · released Nov 2, 2025

Audit

Dependencies

pythonrequiredRequired Python interpreter version for the library.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/amitdev/lru-dict ↗

packagehttps://pypi.org/project/lru-dict/ ↗