Install & Compatibility
Where this runs
tested against v0.41.0 · 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
941MB installed
● package 941MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BaseDoc
✓ from docarray import BaseDoc
✗ from docarray import Document
The `Document` class is part of DocArray's legacy API (pre-0.30.0) and should not be used for new projects. `BaseDoc` is the current base class for custom documents.
DocList
✓ from docarray import DocList
DocVec
✓ from docarray import DocVec
NdArray
✓ from docarray.typing import NdArray
Define custom document schemas using `BaseDoc` and type hints (including `NdArray` for numerical arrays/embeddings), then create instances of single documents or collections using `DocList`.
from docarray import BaseDoc, DocList
from docarray.typing import NdArray
import numpy as np
# 1. Define your custom document schema using BaseDoc
class MyDocument(BaseDoc):
text: str
image_embedding: NdArray[128] # Define an embedding field with fixed dimensions
# 2. Create a single document instance
doc = MyDocument(text='hello world', image_embedding=np.random.rand(128))
print(f"Created document with text: {doc.text}")
# 3. Create a collection of documents using DocList
docs = DocList[MyDocument]([
MyDocument(text='document one', image_embedding=np.random.rand(128)),
MyDocument(text='document two', image_embedding=np.random.rand(128)),
])
print(f"DocList contains {len(docs)} documents.")
# 4. Access individual documents and their fields
print(f"First document's text: {docs[0].text}")
print(f"Second document's embedding shape: {docs[1].image_embedding.shape}")
Errors
Common errors & fixes
ImportError: cannot import name 'Document' from 'docarray'
You are attempting to import the legacy `Document` class which is no longer part of the primary `docarray` namespace for new projects. It has been superseded by `BaseDoc`.
fixReplace `from docarray import Document` with `from docarray import BaseDoc` when defining your document schemas.
AttributeError: 'BaseDoc' object has no attribute 'tags'
Features like `.tags` or `.chunks` were specific to the legacy `Document` class. `BaseDoc` objects are Pydantic models, so custom fields are defined directly.
fixIf you need a 'tags' field, define it explicitly in your `BaseDoc` schema: `class MyDoc(BaseDoc): tags: List[str]`.
TypeError: Object of type DocList is not JSON serializable
Attempting to directly serialize a `DocList` instance using `json.dumps()` without first converting it to a JSON-compatible format like a string or dictionary.
fixUse the built-in `to_json()` method of `DocList` to get a JSON string, then process it. Example: `json_string = my_doclist.to_json()`.
pydantic.error_wrappers.ValidationError: 1 validation error for MyDocument
Your `BaseDoc` model validation failed, often due to providing a value of the wrong type or shape for a field, e.g., passing a list when an `NdArray` is expected.
fixCheck the detailed error message for the specific field causing the validation error. Ensure data types and shapes match your `BaseDoc` schema definitions (e.g., `NdArray[128]` expects a NumPy array of shape (128,)).
Upgrade
Version history
0.41.0latest on PyPI · released Mar 21, 2025
Audit
Dependencies
pydanticrequiredCore dependency for defining document schemas. Supports Pydantic v1 and v2.
numpyrequiredCore dependency, especially for NdArray types.
torchoptionalRequired for `TorchArray`, included in the `full` extra.
tensorflowoptionalRequired for `TensorFlowTensor`, included in the `full` extra.
jaxoptionalRequired for `JaxArray`, included in the `full` extra.