Install & Compatibility
Where this runs
tested against v1.5.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
py 3.10
✕ build_error
✓ 1.5s
py 3.11
✕ build_error
✓ 1.7s
py 3.12
✕ build_error
✓ 1.5s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 1.8s
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DB
✓ db = plyvel.DB(...)
Main class for interacting with a LevelDB database.
This quickstart demonstrates opening a LevelDB database, performing basic put, get, and delete operations, and iterating over stored key-value pairs using `plyvel`. It highlights the recommended practice of using `plyvel.DB` as a context manager for automatic resource management and proper database closing.
import plyvel
import os
import shutil
# Define a path for the LevelDB database
db_path = '/tmp/testdb_plyvel_quickstart'
# Clean up any previous database at the path
if os.path.exists(db_path):
shutil.rmtree(db_path)
try:
# Open a new database, creating it if it doesn't exist
# Using a context manager ensures the database is properly closed
with plyvel.DB(db_path, create_if_missing=True) as db:
print(f"Database opened at: {db_path}")
# Put key-value pairs (keys and values must be bytes)
db.put(b'name', b'Alice')
db.put(b'age', b'30')
db.put(b'city', b'New York')
# Get a value
name = db.get(b'name')
if name:
print(f"Name: {name.decode('utf-8')}")
# Iterate over all key-value pairs
print("\nAll entries:")
for key, value in db:
print(f" {key.decode('utf-8')}: {value.decode('utf-8')}")
# Delete a key
db.delete(b'age')
print("\nAfter deleting 'age':")
# Verify deletion by iterating again
for key, value in db:
print(f" {key.decode('utf-8')}: {value.decode('utf-8')}")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Ensure cleanup even if an error occurs
if os.path.exists(db_path):
shutil.rmtree(db_path)
print(f"\nCleaned up database directory: {db_path}")
Debug
Known issues
breakingPlyvel 1.3.0 (released October 2020) completely dropped support for Python 2. Users migrating to newer Plyvel versions must ensure their projects are running on Python 3.fixUpgrade to Python 3 or pin Plyvel version to <1.3.0 if Python 2 compatibility is essential.
affects: <1.3.0 (for Python 2 support)
gotchaInstalling Plyvel from source (not via pre-built wheels) requires LevelDB development headers and a compatible LevelDB shared library (>= 1.21 for Plyvel 1.4.0+). Failing to provide these can lead to compilation errors or `ImportError` due to undefined symbols. On Linux, `pip install plyvel` often works due to embedded LevelDB in wheels, but if building from source, install `libleveldb-dev` (or equivalent) first.fixUse pre-built binary wheels where available, or install `LevelDB` development headers (e.g., `sudo apt-get install libleveldb-dev`) before `pip install plyvel`.
affects: All versions when building from source
gotchaClosing a `plyvel.DB` instance while it is actively being accessed by other threads can lead to hard crashes due to a lack of internal synchronization. Ensure that no other threads are performing database operations concurrently when calling `DB.close()`.fixAlways ensure exclusive access or use `plyvel.DB` as a context manager (`with plyvel.DB(...) as db:`) which handles closing safely at the end of the block.
affects: All versions
gotchaImplementing custom LevelDB comparators using Python callables in Plyvel incurs a significant performance penalty (e.g., up to a 4x slowdown for bulk writes) compared to LevelDB's native C++ comparators.fixAvoid Python-based custom comparators in performance-critical sections. Rely on LevelDB's default byte-wise comparator or consider alternative key encoding strategies if custom ordering is needed without the performance cost.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'plyvel'
The 'plyvel' package is not installed in the current Python environment.
fatal error: 'leveldb/db.h': No such file or directory
During installation, the 'plyvel' C++ extension cannot find the LevelDB development headers on your system, which are required to build the library from source.
fixInstall the LevelDB development package for your operating system (e.g., `sudo apt-get install libleveldb-dev` on Debian/Ubuntu, `brew install leveldb` on macOS).
plyvel._plyvel.IOError: IO error: lock /path/to/db/LOCK: Resource temporarily unavailable
Another process or a previously unclosed `plyvel.DB` instance is holding a lock on the LevelDB database directory, preventing a new instance from opening it. LevelDB databases can only be opened by one process at a time.
fixEnsure all `plyvel.DB` instances are properly closed using `db.close()` or by using them as context managers (`with plyvel.DB(...) as db:`). Verify no other processes are accessing the database directory.
ImportError: dlopen(/path/to/plyvel/_plyvel.so, 2): Symbol not found: __ZTIN7leveldb10ComparatorE
This 'undefined symbol' error indicates a mismatch between the LevelDB C++ library that 'plyvel' was compiled against and the LevelDB library available on your system at runtime, often due to version incompatibility (e.g., system LevelDB is older than required by Plyvel 1.x, which needs LevelDB >= 1.20).
fixEnsure your system's LevelDB library meets the 'plyvel' version requirements (LevelDB >= 1.20 for Plyvel 1.x). Upgrade your system's LevelDB (e.g., `sudo apt-get install libleveldb-dev libleveldb1v5` or manual installation). Alternatively, install an older 'plyvel' version compatible with your system's LevelDB (`pip install plyvel==<compatible_version>`).
plyvel._plyvel.Error: NotFound: c:/tmp/testdb/LOCK: The system cannot find the path specified
The LevelDB database path is inaccessible, has incorrect permissions, or contains invalid characters, preventing LevelDB from creating its necessary lock file or other files, especially on Windows.
fixEnsure the specified database directory exists and that the Python process has full read/write permissions to it. Use an absolute path. On Windows, complex installation steps for LevelDB and setting environment variables may be necessary if `pip install plyvel` fails to use pre-built wheels.
Upgrade
Version history
1.5.1latest on PyPI · released Jan 15, 2024
Audit
Dependencies
leveldbrequiredCore database engine. Pre-built wheels often embed it; source builds require development headers and shared library.
cythonoptionalRequired for building from source.