clibmdbx

clibmdbx is an independent, high-performance CPython binding for libmdbx. Both the distribution and import name are clibmdbx. It is a community project and is not an official Mithril-mine/libmdbx package.

The hot path is hand-written CPython C API code calling the libmdbx C API directly. The extension embeds the official libmdbx 0.14.3 amalgamation, so a wheel does not load a system libmdbx and has no runtime Python dependencies. It does not use ctypes, CFFI, Cython, Rust, or a helper service.

Stable release: 1.0.1 deliberately uses a CPython-version-specific ABI for maximum hot-path performance. Public API compatibility follows Semantic Versioning within the 1.x line.

Quick start

import clibmdbx

with clibmdbx.Environment("cache.mdbx", max_dbs=8) as env:
    with env.write() as txn:
        txn.put(b"answer", b"42")

    with env.read() as txn:
        assert txn.get(b"answer") == b"42"
        assert txn[b"answer"] == b"42"

Named databases, DUPSORT, cursors and batches use the same transaction model:

with env.write() as txn:
    events = txn.open_db(b"events", flags=clibmdbx.MDBX_DUPSORT, create=True)
    txn.put_many([(b"job", b"started"), (b"job", b"finished")], db=events)

with env.read() as txn, txn.cursor(events) as cursor:
    print(cursor.set(b"job"))
    print(cursor.count())

All keys and values accept bytes or a contiguous bytes-like object. Returned data is copied to safe bytes. MDBX_RESERVE and borrowed zero-copy views are not exposed because their native pointers can outlive neither the write call nor the mapped transaction safely.

Concurrency and lifetime rules

An Environment may be shared by threads. libmdbx still permits only one write transaction at a time per environment.
A Transaction and every cursor belonging to it are bound to the thread that created the transaction. Cross-thread use raises ThreadError before calling libmdbx.
Transactions keep their environment alive; cursors and DB handles keep their owners alive. Closing an environment with active transactions is rejected. A Database.close() closes only that Python view because repeated opens may share one native DBI; ordinary native DBIs remain environment-owned, avoiding upstream's double-close/concurrent-close corruption hazard. Repeated close()/abort() is safe.
A process created with fork() must open a fresh environment. Inherited objects raise ForkError; their destructors intentionally do not call into the parent's native handles.
The current single-phase high-performance extension supports CPython's main interpreter only. Import in a subinterpreter raises ImportError explicitly rather than sharing interpreter-owned exception/type objects unsafely. Use a separate process when interpreter isolation is required.
commit, sync, copy, defragmentation and warm-up release the GIL once around the native operation. A commit with an open cursor retains the GIL because libmdbx updates the transaction's cursor list while committing; close cursors first when concurrent Python progress during commit matters. Warm point reads keep the GIL to avoid a costly release/reacquire on every key. Batch methods cross Python/C once and loop in C. Their default fast path retains the GIL; detached=True first copies every input, then releases the GIL exactly once around the native loop. Use detached mode for cold pages, large batches or latency-sensitive RPC thread pools. Detached mode requires all cursors in the transaction and parent chain to be closed, preventing cross-thread cursor finalization from racing native work.
The wrapper always enables native MDBX_NOSTICKYTHREADS, then applies the stricter Python owner-thread checks itself. Read transactions can therefore be finalized safely by a different Python worker. libmdbx still requires a write transaction to finish on its creator OS thread: an accidental cross-thread final reference is marked broken and queued, never unlocked on the wrong thread. Its owner reaps it automatically on the next environment operation or explicitly with env.reap_orphaned_transactions().
drop(delete=True) is rejected while an unrelated transaction may still reference the shared DBI. It invalidates all duplicate Python aliases after the native delete-and-close succeeds. Creation rolled back at any nesting level likewise invalidates its provisional aliases.

Durability defaults are upstream libmdbx defaults. Unsafe modes such as SAFE_NOSYNC, UTTERLY_NOSYNC, WRITEMAP, and NOMEMINIT are opt-in constants; the binding never enables them silently.

Major APIs

Environment: geometry, options, flags, sync, consistent copy, online defragmentation, warm-up, reader cleanup, statistics and information.
Transaction: read/write/nested transactions, commit timing, abort, reset/renew, refresh, park/unpark, canary, GC information, DB enumeration, CRUD, replace and batch operations.
Database: flags/statistics, sequence, clear/drop, close and rename.
Cursor: exact/range positioning, forward/reverse and DUPSORT traversal, count, write/delete/renew, iterator protocol and bounded range collection.
Stable exception classes for common libmdbx failures, plus ThreadError, ForkError, and ClosedError for wrapper safety checks. Native exceptions include code, what, and reason, matching the diagnostic ergonomics expected from mature LMDB bindings.

See the complete C API coverage matrix, the API/lifecycle guide, the wtdcode/mdbx-py ctypes compatibility audit, the python-lmdb comparison, and the benchmark method.

Build and verify from source

A C11 compiler and CPython development headers are required. Builds use the vendored source and perform no network access.

python -m venv .venv
. .venv/bin/activate
python -m pip install -U pip build pytest twine
python -m pip install -e .
python -m pytest -q
python -m build
python -m twine check dist/*

Strict warnings are enabled by default. Sanitizer builds are supported on Clang/GCC:

CLIBMDBX_SANITIZE=address,undefined python -m pip install -e . --no-build-isolation
ASAN_OPTIONS=detect_leaks=0:abort_on_error=1 \
UBSAN_OPTIONS=halt_on_error=1 PYTHONMALLOC=malloc python -m pytest -q

For source provenance, wheel policy, release commands, and supported-platform evidence, see VENDORING.md, docs/BUILDING.md, and RELEASING.md.

Embedded source and license

This source tree pins official libmdbx 0.14.3, upstream release tag v0.14.3. The release tag resolves to commit f7a3a9323cacacfa9dc6137ae7a7252a67744ff0; the official amalgamation records source commit 251562b2dc55266d8e6d0e6627ec88ecb410702f. The official amalgamation archive SHA-256 is dbc4a791c44d3e51a8159eedfee0dedada7b21d46c22588f0fa99294983f33cd.

The wrapper and libmdbx are Apache-2.0 licensed. The sdist and wheels retain the wrapper and upstream LICENSE, NOTICE, and COPYRIGHT; see THIRD_PARTY_NOTICES.md and SBOM.cdx.json.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

clibmdbx-1.0.1.tar.gz (632.5 kB view details)

Uploaded Aug 29, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

clibmdbx-1.0.1-cp314-cp314-win_amd64.whl (282.4 kB view details)

Uploaded Aug 29, 2026 CPython 3.14Windows x86-64

clibmdbx-1.0.1-cp314-cp314-manylinux_2_28_x86_64.whl (1.3 MB view details)

Uploaded Aug 29, 2026 CPython 3.14manylinux: glibc 2.28+ x86-64

clibmdbx-1.0.1-cp314-cp314-manylinux_2_28_aarch64.whl (1.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.14manylinux: glibc 2.28+ ARM64

clibmdbx-1.0.1-cp314-cp314-macosx_11_0_arm64.whl (243.8 kB view details)

Uploaded Aug 29, 2026 CPython 3.14macOS 11.0+ ARM64

clibmdbx-1.0.1-cp314-cp314-macosx_10_15_x86_64.whl (251.2 kB view details)

Uploaded Aug 29, 2026 CPython 3.14macOS 10.15+ x86-64

clibmdbx-1.0.1-cp313-cp313-win_amd64.whl (276.9 kB view details)

Uploaded Aug 29, 2026 CPython 3.13Windows x86-64

clibmdbx-1.0.1-cp313-cp313-manylinux_2_28_x86_64.whl (1.3 MB view details)

Uploaded Aug 29, 2026 CPython 3.13manylinux: glibc 2.28+ x86-64

clibmdbx-1.0.1-cp313-cp313-manylinux_2_28_aarch64.whl (1.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.13manylinux: glibc 2.28+ ARM64

clibmdbx-1.0.1-cp313-cp313-macosx_11_0_arm64.whl (243.7 kB view details)

Uploaded Aug 29, 2026 CPython 3.13macOS 11.0+ ARM64

clibmdbx-1.0.1-cp313-cp313-macosx_10_13_x86_64.whl (251.1 kB view details)

Uploaded Aug 29, 2026 CPython 3.13macOS 10.13+ x86-64

clibmdbx-1.0.1-cp312-cp312-win_amd64.whl (276.9 kB view details)

Uploaded Aug 29, 2026 CPython 3.12Windows x86-64

clibmdbx-1.0.1-cp312-cp312-manylinux_2_28_x86_64.whl (1.3 MB view details)

Uploaded Aug 29, 2026 CPython 3.12manylinux: glibc 2.28+ x86-64

clibmdbx-1.0.1-cp312-cp312-manylinux_2_28_aarch64.whl (1.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.12manylinux: glibc 2.28+ ARM64

clibmdbx-1.0.1-cp312-cp312-macosx_11_0_arm64.whl (243.8 kB view details)

Uploaded Aug 29, 2026 CPython 3.12macOS 11.0+ ARM64

clibmdbx-1.0.1-cp312-cp312-macosx_10_13_x86_64.whl (251.2 kB view details)

Uploaded Aug 29, 2026 CPython 3.12macOS 10.13+ x86-64

clibmdbx-1.0.1-cp311-cp311-win_amd64.whl (276.8 kB view details)

Uploaded Aug 29, 2026 CPython 3.11Windows x86-64

clibmdbx-1.0.1-cp311-cp311-manylinux_2_28_x86_64.whl (1.3 MB view details)

Uploaded Aug 29, 2026 CPython 3.11manylinux: glibc 2.28+ x86-64

clibmdbx-1.0.1-cp311-cp311-manylinux_2_28_aarch64.whl (1.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.11manylinux: glibc 2.28+ ARM64

clibmdbx-1.0.1-cp311-cp311-macosx_11_0_arm64.whl (243.5 kB view details)

Uploaded Aug 29, 2026 CPython 3.11macOS 11.0+ ARM64

clibmdbx-1.0.1-cp311-cp311-macosx_10_9_x86_64.whl (250.3 kB view details)

Uploaded Aug 29, 2026 CPython 3.11macOS 10.9+ x86-64

clibmdbx-1.0.1-cp310-cp310-win_amd64.whl (277.0 kB view details)

Uploaded Aug 29, 2026 CPython 3.10Windows x86-64

clibmdbx-1.0.1-cp310-cp310-manylinux_2_28_x86_64.whl (1.3 MB view details)

Uploaded Aug 29, 2026 CPython 3.10manylinux: glibc 2.28+ x86-64

clibmdbx-1.0.1-cp310-cp310-manylinux_2_28_aarch64.whl (1.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.10manylinux: glibc 2.28+ ARM64

clibmdbx-1.0.1-cp310-cp310-macosx_11_0_arm64.whl (243.6 kB view details)

Uploaded Aug 29, 2026 CPython 3.10macOS 11.0+ ARM64

clibmdbx-1.0.1-cp310-cp310-macosx_10_9_x86_64.whl (250.4 kB view details)

Uploaded Aug 29, 2026 CPython 3.10macOS 10.9+ x86-64

File details

Details for the file clibmdbx-1.0.1.tar.gz.

File metadata

Download URL: clibmdbx-1.0.1.tar.gz
Upload date: Aug 29, 2026
Size: 632.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for clibmdbx-1.0.1.tar.gz
Algorithm	Hash digest
SHA256	`69351dec40b26f9d3d7bc3067f7ab9719cc004752b024f35fa9d0c7c47a68940`
MD5	`71d53b0d3a946853641e16c8caed2432`
BLAKE2b-256	`828e108318d023f94e9581c68f06b51b07dd84daa0d337ca9383129cafad6037`

Algorithm	Hash digest
SHA256	`cdae529ac4ed8be2b3c9bb0dd7901ab19480beafb5804d2e1057696cab6f643c`
MD5	`fbacb145e277db771a43161afc4a97c7`
BLAKE2b-256	`ac8ad40a1db9c4444f6de9e63b7b5b1090ef848ed2827ac330e2eed1435f01c8`

Algorithm	Hash digest
SHA256	`5b8157360bac024ad033e23aded3734d509601bae939d2b0d9a0fe3621c1bb4d`
MD5	`8da380dbff752cd53c2af679b9a728ef`
BLAKE2b-256	`b879158a9c08e97ac782fad414a7844aab795feb9108fd8d3641a0a672a79830`

Algorithm	Hash digest
SHA256	`9e4d29a6c01968c6ff5dd2fb5185ff43db78979fa5353117b8918a2bec938c4c`
MD5	`34d22dea003bab7a03586017455fafcb`
BLAKE2b-256	`ea77c88330cdae01709059a40d96351d4adf2307fbde261e6fe6b4192d61e47d`

Algorithm	Hash digest
SHA256	`fd3d3a1e2a6cd8f577fb3e50323675420822854de8d9a5c86e0797e33e68394e`
MD5	`8acafc6ea16078caf2ce30d818ce9bfd`
BLAKE2b-256	`e37648963d3e18940b9b20dc9728bd8705a7cea3c60c37688d0d1687c28a8035`

Algorithm	Hash digest
SHA256	`797f0427bfd156784e1eef452cced1098c9f9cef64ad98f21a30ef0c2c37aa28`
MD5	`310c24dbb47cd47fd45c8f1fe4eaa81b`
BLAKE2b-256	`ec48b6a4d14d98e38d4509612f4809b2b745565f187e87a980ab14f98c075ec9`

Algorithm	Hash digest
SHA256	`a0fb99dc5d9b7af74491fa35936ed42809416072c5dd2bbfa06576f9f093d865`
MD5	`47cbfc9b8d6b7e5871786be75b0a5b54`
BLAKE2b-256	`868af3514677fc11b9ae403d34839166db024474961b59cffdb04c13be02b3c9`

Algorithm	Hash digest
SHA256	`5a88ca7bc122c17c497f627f283b6b1ac41d7ed2cbcc689c14e99c5d57047f24`
MD5	`b2231689e728851c8ec73abc64e633dc`
BLAKE2b-256	`28706ceff3fb56c19abf76675a80943941824c3364c826cd75284da268d82ae6`

Algorithm	Hash digest
SHA256	`32851c4e04e5b6b1ab0d2da86e54083e7ee509b2a41bfdd27ab3cbed60472262`
MD5	`8652c32a84942fcbbb1162dabd3a5081`
BLAKE2b-256	`25e41d47efbb94f87538524849f46532c2662cab406b727351e303ac48b84386`

Algorithm	Hash digest
SHA256	`e3d961c02e38c73e3323fa55830d197316d64e9e4db3155477cc9a64568d05e3`
MD5	`b32b1bc7572447146ce37a7cdae4d3ae`
BLAKE2b-256	`b860bbf880053b2d46f7cf2e4b8d3989f1e382c3cfb99f005216217e4d105a82`

Algorithm	Hash digest
SHA256	`1d07e5ce346347bc0085bd3b8aa0297f7823883d6fc994aa08925ac3618e6c8a`
MD5	`eba565b7c622e02365e73df28e49b0d9`
BLAKE2b-256	`94492a8f5b49502fbe2d7f149f422c031e36b5717f02a054a732233c973a63d9`

Algorithm	Hash digest
SHA256	`782ce188b3a480349aae0fe84255d507265f99af8e36a2422e15d7565d55f948`
MD5	`cee547d8f19dc646619fbb01de4ed938`
BLAKE2b-256	`f1708d2ff0506e81aacd65b0290048e63f8f0e682d91cdfd7b9012426f5d46ab`

Algorithm	Hash digest
SHA256	`43679b341e4946c95a07e917bf17f3da5d8eea56079387a18aa3a8e4da956aa9`
MD5	`96378163ad8e1a30a18f0fbb345dfe87`
BLAKE2b-256	`817c31d67d3ef7e2369c088d4d472e7d2570020a452936af0d0970e1e18dbc12`

Algorithm	Hash digest
SHA256	`43d40412fa8c5a76e54c7e37221a5bd1af1621cdaa73a724036889e4e7c8b9e0`
MD5	`2874912819513ea368fa389559c629b2`
BLAKE2b-256	`65c7a53a72c5b97d08a268634afa6134e29458795551986426b2ab05590b78f1`

Algorithm	Hash digest
SHA256	`c022217391ea4c404dfbc2196af755031748ab1c6b9d77eabd273a142535a0bf`
MD5	`c72141fb23956ee9f2dcbadacee30390`
BLAKE2b-256	`96dfde5d4af5bb7c9059c9bde0e2780e4f822b40c73ba97e61393d2313d32e3f`

Algorithm	Hash digest
SHA256	`5345a337d316c16c198dd72dd23f5ce37f3907534bbcd9244e19392498057620`
MD5	`b497d494fbb62c130ce33a54218a80b6`
BLAKE2b-256	`b7876081bd4792b6812dd39c9c9726762ac99155c5c19ea9b0eb2f3987af85ee`

Algorithm	Hash digest
SHA256	`913aeb4b75117cec4c9d26fccd032130264e8bf8ea4e2db21e3a960bc30b7829`
MD5	`d62bf0a15b321ced9e1bc80b0321a880`
BLAKE2b-256	`a5fcc7eddcb6e15be1392e90758481fe23143897d4263d2121a57455fcf6bb4f`

Algorithm	Hash digest
SHA256	`3b78891d2c711eadbe0aa7ddbed07abd120b7ecb014690c0acaa6fb292a6405a`
MD5	`d3bd9c5a4f8f996d308e716ff0de8305`
BLAKE2b-256	`b48af09433564bc835e6609b880463838cfc08a73fcb222bfcf5b85e8e41dc65`

Algorithm	Hash digest
SHA256	`8242545a2d71f41bc81e5d2f45858c2fc1dc0c52ee82e429f62dfb09a5e36711`
MD5	`8894bef7cf9c4acad1703c1e210dd12e`
BLAKE2b-256	`0efe3af5f1af9030b0465d4844041bf57b8cd3f414258ae16cf89727248fac6f`

Algorithm	Hash digest
SHA256	`d3a915b42b59e93ea2dde3809b3c05a4621b996a9f247af0de539a5d7d168511`
MD5	`dbf47fcc2065de208acd9d26757dcda7`
BLAKE2b-256	`97ec9d76f183c568f3ecab41c481aa2cd7594ebc063a411f75c885dcbe777799`

Algorithm	Hash digest
SHA256	`e1345488dc1849b5b580fac28b45ac8368ad785a9413631bb28441675f4f946b`
MD5	`bf27f6b9fe2b4bed9d9943eec6752248`
BLAKE2b-256	`25e78aa4cea5384f44674b167965eb692be40c9ecb40713863a69441e9bf3238`

clibmdbx 1.0.1

clibmdbx

Quick start

Concurrency and lifetime rules

Major APIs

Build and verify from source

Embedded source and license

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

Algorithm	Hash digest
SHA256	`5cea5a4faa9324ce9f6a154a74fcbfb1959874c893301d30f2bd2d6c986d4b53`
MD5	`f717a31ae2753a24c330025ccedbb442`
BLAKE2b-256	`e50f74c4d7f438e41e7096076d962ce4707f77d0b8d4b985b146fd44914b3645`

Algorithm	Hash digest
SHA256	`9b4b6327f281f3a15ff587c436efe981dcd8710d729cd62e21eb07984f197f57`
MD5	`5aa1fb3dab4be23cc2975d5d6ebd66df`
BLAKE2b-256	`6ac1d9ac25fb4bc2f17c25473f7a6d30db2416bd6241afbec3581cb91a3de6e4`

Algorithm	Hash digest
SHA256	`0d254dc65872f11ba109600ceff0f904379a2b06a24d325724bd797dff9fd812`
MD5	`e8d83255d3ff1aff425c7109cd17499f`
BLAKE2b-256	`9a94a8128f7f6564ed391f781714862afed1d7cbac6c485ffbdae675e7407492`

Algorithm	Hash digest
SHA256	`5f5801b1db5999660a076896d8dc8bc9d91595648f39499c1266501da1fcc3a3`
MD5	`7ee0a538a10113dd3bb472a7d3c24e18`
BLAKE2b-256	`86147707836001638da691c5c8c119666f75a29ae3992c429297a15b85ac7989`

Algorithm	Hash digest
SHA256	`b4aa7bd51caea427829307fc5f58747ea6d7b3fb10960157b156135216122d2e`
MD5	`8cc36c272ba04acf9a74f5e990f0a7fd`
BLAKE2b-256	`a04a0b533a52aca5bb6bb3dcfaced52ac7f219418e17760fcf29752d052a524a`