Install & Compatibility
Where this runs
tested against v0.14.4 · 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.9
✕ build_error
✓ 3.5s
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Doc
✓ from pycrdt import Doc
The primary class for creating and managing a shared document.
Text
✓ from pycrdt import Text
A CRDT type similar to a string, for collaborative text editing.
Array
✓ from pycrdt import Array
A CRDT type similar to a list, for collaborative array manipulation.
Map
✓ from pycrdt import Map
A CRDT type similar to a dictionary, for collaborative key-value storage.
This quickstart demonstrates how to initialize a `pycrdt.Doc`, interact with its shared data types (`Text`, `Array`, `Map`), and synchronize changes between two document replicas by exchanging updates.
from pycrdt import Doc, Text, Array, Map
# Create a shared document
doc0 = Doc()
# Get or create root types for collaborative data
text0 = doc0.get("text", type=Text)
array0 = doc0.get("array", type=Array)
map0 = doc0.get("map", type=Map)
# Make changes to the document within a transaction
with doc0.transaction():
text0.insert(0, "hello")
array0.append()
map0["key1"] = "value1"
# Get the updates from doc0
updates = doc0.get_update()
# Simulate another client or replica
doc1 = Doc()
# Apply updates from doc0 to doc1
doc1.apply_update(updates)
# Verify the state of doc1
text1 = doc1.get("text", type=Text)
array1 = doc1.get("array", type=Array)
map1 = doc1.get("map", type=Map)
print(f"Doc1 Text: {text1}")
print(f"Doc1 Array: {array1}")
print(f"Doc1 Map: {map1}")
# Make further changes on doc1 concurrently
with doc1.transaction():
text1.insert(5, " world")
array1.append()
map1["key2"] = "value2"
# Get updates from doc1, relative to doc0's initial state for merging
updates_from_doc1 = doc1.get_update(doc0.get_state())
# Apply updates from doc1 back to doc0
doc0.apply_update(updates_from_doc1)
# Verify doc0 has the merged state
print(f"Doc0 Text (merged): {doc0.get('text', type=Text)}")
print(f"Doc0 Array (merged): {doc0.get('array', type=Array)}")
print(f"Doc0 Map (merged): {doc0.get('map', type=Map)}")
Debug
Known issues
breakingPython 3.9 support was dropped in version 0.12.37.fixUpgrade to Python 3.10 or newer.
affects: 0.12.37 and later
breakingPyPy 3.10 support was dropped in version 0.12.41.fixSwitch to a CPython environment or use an older `pycrdt` version if PyPy 3.10 is required. Python 3.10+ CPython is recommended.
affects: 0.12.41 and later
gotchaPrior to version 0.12.50, there could be issues with concurrent async transactions that might lead to unexpected behavior.fixEnsure you are using `pycrdt` version 0.12.50 or newer for robust concurrent async transaction handling.
affects: <0.12.50
gotchaBefore version 0.12.48, tuples assigned to `Map` entries were incorrectly handled and converted to 'undefined' in the underlying Yrs structure.fixUpgrade to `pycrdt` 0.12.48 or later. If using tuples, ensure they are converted to lists before assignment if compatibility with older versions or other Yjs clients is critical for that specific data type.
affects: <0.12.48
gotchaPrior to version 0.12.45, exceptions raised within observer callbacks (e.g., `observe`, `observe_deep`) were not grouped. A single exception could halt further callback execution.fixUpdate to `pycrdt` 0.12.45 or newer, which now collects all exceptions from observer callbacks into an `ExceptionGroup` for more resilient error handling.
affects: <0.12.45
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pycrdt'
The 'pycrdt' library is not installed in your current Python environment, or your Python environment is not correctly activated.
fixEnsure you have the correct Python environment active and install the library using pip: `pip install pycrdt`
AttributeError: module 'pycrdt' has no attribute 'Doc'
You are attempting to access a class or object (like 'Doc') directly from the top-level 'pycrdt' module, but it needs to be explicitly imported from its submodule.
fixImport the specific class or object directly from the library: `from pycrdt import Doc`
TypeError: 'str' object cannot be interpreted as an integer
This typically occurs when attempting to use a string as an index for a `pycrdt.Array` or a similar operation that expects an integer, or when passing an incorrect type to a method expecting a specific numeric type.
fixEnsure that arguments provided to methods like `Array.insert()` or when indexing are of the correct type, e.g., use an integer `0` instead of a string `'0'`.
Upgrade
Version history
0.14.4latest on PyPI · released Aug 23, 2026
Audit
Dependencies
No dependency data recorded yet.