Bidirectional Mapping Library

raw JSON →
0.23.1 verified Tue May 12 auth: no python install: verified

The bidict library for Python provides efficient and Pythonic data structures for working with bidirectional (one-to-one) mappings. It offers familiar dictionary-like APIs, automatically keeping forward and inverse mappings in sync. The library is mature, actively maintained, and currently at version 0.23.1, with a regular release cadence. [1, 3, 10]

pip install bidict

Common errors

error ModuleNotFoundError: No module named 'bidict' ↓
cause The `bidict` library is not installed in the Python environment, or the Python interpreter being used cannot find it.
fix
Install the library using pip: pip install bidict
error bidict.ValueDuplicationError: <value> ↓
cause This error occurs when attempting to add an item to a `bidict` where the value already exists, violating the bidirectional uniqueness constraint.
fix
Ensure all values inserted into a bidict are unique. If overwriting is desired, use forceput() or specify an appropriate OnDupAction with put(), for example: b.forceput('new_key', 'existing_value') or b.put('new_key', 'existing_value', on_dup=bidict.OnDup(val=bidict.ON_DUP_DROP_OLD)).
error TypeError: unhashable type: 'list' ↓
cause Bidict requires both keys and *values* to be hashable because it maintains an inverse mapping where values become keys. Unhashable types like lists or dictionaries cannot be used as values.
fix
Use hashable types for values, such as tuples, frozensets, strings, numbers, or custom objects that implement __hash__ and __eq__ methods. For example, replace ['opt', 'pot', 'top'] with ('opt', 'pot', 'top').
error TypeError: 'frozenbidict' object does not support item assignment ↓
cause `frozenbidict` is an immutable version of `bidict`, meaning its contents cannot be changed after creation.
fix
Use the mutable bidict type if you need to modify the mapping after creation, or create a new frozenbidict with the desired changes.
error AttributeError: module 'bidict' has no attribute 'OVERWRITE' ↓
cause The API for handling duplication actions changed in `bidict`. Older constants like `OVERWRITE` have been replaced by the `OnDupAction` enum and related constants (e.g., `ON_DUP_DROP_OLD`, `ON_DUP_RAISE`).
fix
Update your code to use the modern OnDupAction enum or its predefined instances. For example, replace bidict.OVERWRITE with bidict.ON_DUP_DROP_OLD when using methods like put() or putall().

Warnings

breaking The `.inv` attribute for accessing the inverse mapping was renamed to `.inverse`. While `.inv` was an alias for a period, it's recommended to use `.inverse` for clarity and future compatibility. ↓
fix Replace `.inv` with `.inverse`.
breaking Support for Python 3.6 was dropped. If you are using bidict with Python 3.6, you must remain on an older version of the library or upgrade your Python interpreter. ↓
fix Upgrade to Python 3.8+ (recommended `bidict` requirement) or ensure your `bidict` version is pinned to <0.22.0.
breaking Several old APIs, including the `on_dup_key`, `on_dup_val`, and `on_dup_kv` arguments to `put()` and `putall()`, as well as the constants `bidict.OVERWRITE` and `bidict.IGNORE`, were removed. ↓
fix Consult the changelog for `bidict` 0.20.0 for alternative approaches to handling duplicate key/value scenarios. [2]
gotcha Unlike standard `dict` values, values stored in a `bidict` must be hashable. This is because values serve as keys in the inverse mapping, and keys must always be hashable in Python dictionaries. ↓
fix Ensure that any values you intend to store in a `bidict` are immutable and hashable (e.g., strings, numbers, tuples). [6]
gotcha For `OrderedBidict`, the `==` operator (`__eq__`) performs an order-insensitive comparison, similar to regular `dict`s. If you require order-sensitive equality checking, use the `equals_order_sensitive()` method. ↓
fix Use `my_ordered_bidict.equals_order_sensitive(other_bidict)` for order-aware comparisons. [9, 14]
gotcha Attempting to create a bidirectional mapping using two separate `dict`s or a single `dict` with duplicated key/value entries is error-prone and leads to manual synchronization issues and potential data inconsistency. `bidict` handles these invariants automatically. ↓
fix Always use `bidict` for one-to-one bidirectional mappings to ensure consistency and correctness. [1, 4, 6]
deprecated The `bidict.__version_info__` attribute was removed. ↓
fix Use `import importlib.metadata; importlib.metadata.version('bidict')` or `bidict.__version__` to get the version string. [2]

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 0.02s 18.0M
3.10 alpine (musl) - - 0.02s 18.0M
3.10 slim (glibc) wheel 1.5s 0.01s 18M
3.10 slim (glibc) - - 0.01s 18M
3.11 alpine (musl) wheel - 0.03s 19.8M
3.11 alpine (musl) - - 0.04s 19.8M
3.11 slim (glibc) wheel 1.6s 0.03s 20M
3.11 slim (glibc) - - 0.03s 20M
3.12 alpine (musl) wheel - 0.02s 11.7M
3.12 alpine (musl) - - 0.02s 11.7M
3.12 slim (glibc) wheel 1.4s 0.02s 12M
3.12 slim (glibc) - - 0.02s 12M
3.13 alpine (musl) wheel - 0.02s 11.4M
3.13 alpine (musl) - - 0.02s 11.3M
3.13 slim (glibc) wheel 1.5s 0.02s 12M
3.13 slim (glibc) - - 0.02s 12M
3.9 alpine (musl) wheel - 0.01s 17.5M
3.9 alpine (musl) - - 0.02s 17.5M
3.9 slim (glibc) wheel 1.8s 0.01s 18M
3.9 slim (glibc) - - 0.01s 18M

Imports

Quickstart last tested: 2026-04-24

This example demonstrates creating a basic bidirectional mapping, accessing forward and inverse entries, and observing how updates are automatically synchronized. [3, 10]

from bidict import bidict

element_by_symbol = bidict({'H': 'hydrogen'})
print(f"Forward mapping: {element_by_symbol['H']}")
print(f"Inverse mapping: {element_by_symbol.inverse['hydrogen']}")

# Updates are automatically synchronized in both directions
element_by_symbol['H'] = 'hydrogène'
print(f"Updated forward mapping: {element_by_symbol['H']}")
print(f"Updated inverse mapping: {element_by_symbol.inverse['hydrogène']}")
last verified Tue May 12
next check Sat Jun 27