rocksdict

library0.3.29pypypi✓ verified 87d ago

RocksDict provides a Python binding for RocksDB, offering an efficient on-disk key-value storage solution. It enables users to store, query, and delete a large number of key-value pairs that may not fit into RAM. The library supports storing various Python objects (with Pickle) in its default mode and raw bytes in its raw mode. It also functions as an interface to inspect RocksDB databases created by other languages. The current version is 0.3.29, with a release cadence that includes frequent updates for Python version support and new features.

database serialization

pip install rocksdict

package ↗

INSTALL

IMPORT

SIG · ROCKSDICT

rocksdict

databasepythonv0.3.29

Install

1.9s avg

Import

3ms

Disk

28MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.29 · 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.920 runs

installs and imports cleanly · install 0.0s · import 0.001s · 32MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.9s · import 0.000s · 29MB

28MB installed

● package 28MB

Code

Verified usage

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

Rdict

✓ from rocksdict import Rdict

Options

✓ from rocksdict import Options

This quickstart demonstrates how to create a RocksDict, store various data types, retrieve values, close and reopen the database, iterate through its contents, and finally clean up by destroying the database.

import os from rocksdict import Rdict, Options path = str("./my_test_db") # Ensure clean start for example if os.path.exists(path): Rdict(path).destroy() # Create an Rdict with default options db = Rdict(path) # Store various Python objects db[1] = "value_one" db["key_two"] = 25 db[b"binary_key"] = b"binary_value" db["list_key"] = [1, 2, 3] db["dict_key"] = {"a": 1, "b": 2} print(f"Value for key_two: {db['key_two']}") # Reopen Rdict from disk after closing db.close() db = Rdict(path) print(f"Value for list_key after reopen: {db['list_key']}") # Iterate through items print("\nItems in the database:") for k, v in db.items(): print(f"{k} -> {v}") # Delete an item del db[1] assert 1 not in db # Destroy the database (clean up) db.destroy()

Debug

Known issues

breakingThe methods `Options.set_ignore_range_deletions` and `Options.set_skip_checking_sst_file_sizes_on_db_open` have been removed. Code using these methods will break.

fix

Remove calls to these deprecated `Options` methods. Consult RocksDB documentation for alternative configurations if needed.

affects: >=0.3.29 (associated with Python 3.14+ updates)

gotchaWhen opening an existing RocksDB database created by other languages (C++, Java, etc.), `rocksdict` automatically defaults to 'Raw Mode' since v0.3.24b2. In Raw Mode, only bytes can be stored or retrieved as keys and values. Attempting to use Python objects will fail if not manually handled.

fix

Be aware of the mode when interacting with externally created databases. If non-byte Python objects are expected, ensure your application handles serialization/deserialization or re-evaluate the use of Raw Mode.

affects: >=0.3.24b2

gotchaRocksDict currently does not have good support for `merge` operations or custom comparators directly within its Python interface. While RocksDB supports these features, they are not fully exposed or easily usable in `rocksdict`.

fix

Avoid relying on RocksDB's merge operators or custom comparators when using `rocksdict`. Implement read-modify-write patterns at the application level if merge-like behavior is required, acknowledging potential performance implications and concurrency challenges.

affects: All versions

gotchaWhen working with large datasets, especially if processes crash, you might encounter 'Corruption: Corrupt or unsupported format_version' or 'IO error: lock hold by current process' errors. This indicates data corruption or issues with database locks.

fix

Always call `db.close()` before attempting operations like `db.repair(path)`. Ensure robust error handling and proper shutdown procedures in your application to minimize the risk of corruption. Consider using transactions or backups for critical data.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'rocksdict'

The 'rocksdict' package is not installed in the current Python environment.

fix

pip install rocksdict

rocksdict.exceptions.RocksDictException: IO error: lock /some/path/to/db/LOCK: Resource temporarily unavailable

Another process is currently holding a lock on the RocksDB database at the specified path, preventing `rocksdict` from opening or accessing it.

fix

Ensure no other process is using the database, or explicitly close previous connections if they weren't shut down cleanly. If a process crashed, you might need to manually delete the 'LOCK' file within the database directory.

TypeError: key must be str or bytes

When interacting with `rocksdict`, keys must always be either a string (`str`) or bytes (`bytes`). The provided key's type does not meet this requirement.

fix

Convert the key to a string or bytes before using it (e.g., `str(your_key)` or `your_key.encode('utf-8')`).

AttributeError: 'RocksDict' object has no attribute 'set'

The `rocksdict` library uses the method `put()` for inserting or updating key-value pairs, rather than a `set()` method.

fix

Use `db.put(key, value)` instead of `db.set(key, value)` to store data in the RocksDict instance.

Upgrade

Version history

0.3.29latest on PyPI · released Dec 1, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/rocksdict/ ↗