Registry / database / lmdb
library2.3.0pypypi✓ verified 24d ago

lmdb (py-lmdb) is a universal Python binding for the LMDB 'Lightning' Database, a fast, memory-efficient, embedded key-value store. It provides an ordered map interface, multi-version concurrency control (MVCC) with reader/writer transactions, and utilizes memory-mapped files for zero-copy operations. The library is actively maintained, with frequent releases; the current version is 2.2.0.

pip install lmdb
INSTALL
IMPORT
SIG · LMDB
L
lmdb
databasepythonv2.3.0
Install
1.7s avg
Import
Disk
17MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.3.0 · 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.103.95 runs
build_error
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.7s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage

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

lmdb
import lmdb

This quickstart demonstrates how to open an LMDB environment, write key-value pairs, read specific values, iterate through all entries using a cursor, and properly close the environment. Note the use of byte strings for keys and values, and the importance of `map_size` and `max_dbs` configuration. The example also includes basic cleanup.

import lmdb import os import shutil db_path = './my_lmdb_data' # Ensure cleanup for demonstration if os.path.exists(db_path): shutil.rmtree(db_path) # 1. Open an LMDB environment # map_size: Maximum size of the database. Crucial to set correctly. # max_dbs: Max number of named databases (sub-databases). env = lmdb.open(db_path, map_size=10*1024*1024, max_dbs=10, subdir=True) # 2. Write data to the database with env.begin(write=True) as txn: txn.put(b'my_key_1', b'my_value_1') txn.put(b'my_key_2', b'my_value_2') txn.put(b'another_key', b'another_value') print("Wrote data to LMDB.") # 3. Read data from the database with env.begin() as txn: value1 = txn.get(b'my_key_1') value_non_existent = txn.get(b'non_existent_key') print(f"Value for my_key_1: {value1.decode('utf-8') if value1 else None}") print(f"Value for non_existent_key: {value_non_existent}") # Iterate through all key-value pairs print("\nAll items in DB:") for key, value in txn.cursor(): print(f" {key.decode('utf-8')}: {value.decode('utf-8')}") # 4. Close the environment env.close() print("\nLMDB environment closed.") # Cleanup (optional, for examples) if os.path.exists(db_path): shutil.rmtree(db_path) print(f"Cleaned up database at {db_path}")
Debug
Known issues
gotchaKeys and values in LMDB must be byte strings. Python strings (unicode) need to be explicitly encoded (e.g., `s.encode('utf-8')`) before being stored, and decoded (`b.decode('utf-8')`) after retrieval.
fix
Always `.encode()` Python strings to bytes before `put()` and `.decode()` bytes to strings after `get()` or cursor iteration.
affects: All versions
gotchaThe `map_size` parameter in `lmdb.open()` sets the maximum size of the database. It is crucial to set this value sufficiently large upfront, especially if the database is opened by multiple processes. Modifying `map_size` from multiple processes concurrently can lead to catastrophic data loss.
fix
Estimate your maximum database size and set `map_size` generously when initially opening the environment. Ensure `map_size` is consistent if multiple processes access the same database. If resizing is necessary, ensure only one process is active.
affects: All versions
gotchaWhen using named databases (sub-databases), the `max_dbs` parameter must be set in `lmdb.open()` during the *first* opening of the environment by any process or thread. This allocates shared memory resources for the maximum number of named databases.
fix
Determine the maximum number of named databases you will use and specify `max_dbs` in `lmdb.open()` when the environment is created or first accessed.
affects: All versions
gotchaWrite transactions (`env.begin(write=True)`) must be committed using `txn.commit()`. If not explicitly committed (e.g., if an exception occurs within the `with` block without proper handling), changes will be rolled back by default.
fix
Always use `with env.begin(write=True) as txn:` for write operations. The context manager handles `commit()` on success and `abort()` on exceptions automatically.
affects: All versions
breakingVersion 1.4.1 and newer of `py-lmdb` dropped support for Python 2.x and older Python 3.x versions. Specifically, Python 3.9 or newer is now required.
fix
Ensure your project runs on Python 3.9 or a newer compatible version. For older Python environments, use `py-lmdb < 1.4.1` (e.g., `pip install 'lmdb<1.4.1'`).
affects: 1.4.1 and above
Errors
Common errors & fixes
MDB_MAP_FULL: Environment mapsize limit reached
The LMDB environment's allocated memory map size is not large enough to accommodate new data or database growth.
fix
Increase the `map_size` parameter when opening the LMDB environment to a sufficiently large value (e.g., `lmdb.open(path, map_size=1_000_000_000)` for 1GB), or use `env.set_mapsize()` to dynamically expand it.
ModuleNotFoundError: No module named 'lmdb'
The `lmdb` Python package is not installed or is not accessible in the current Python environment.
fix
Install the package using pip: `pip install lmdb`. Ensure you are running this in the correct Python environment if using virtual environments.
TypeError: Won't implicitly convert Unicode to bytes; use .encode()
LMDB works with byte strings for keys and values, but a Unicode string was passed without explicit encoding.
fix
Explicitly encode Unicode strings to byte strings (e.g., UTF-8) before passing them to LMDB operations: `key.encode('utf-8')` or `value.encode('utf-8')`.
lmdb.Error: The environment '' is already open in this process
An attempt was made to open an LMDB environment that is already open within the same Python process, which can lead to corruption or unexpected behavior.
fix
Ensure that `lmdb.open()` is called only once per environment per process. If you need to re-access it, use the existing environment object. If multiprocessing, open a fresh `Environment` in each child process or use `multiprocessing.get_context('spawn')`.
Upgrade
Version history
2.3.0latest on PyPI · released Jul 12, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
3 hits · last 30 days
node
2
Resources
lmdb — pip install lmdb · libregistry