Install & Compatibility
Where this runs
tested against v0.38.0b10 · 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.10
✕ build_error
3/4 runs
py 3.11
✕ build_error
3/4 runs
py 3.12
✕ build_error
3/4 runs
py 3.13
✕ build_error
✓ 33s
py 3.9
✕ build_error
3/4 runs
5939MB installed
● package 5939MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
lancedb
✓ import lancedb
Top-level import works. Use lancedb.connect() for sync or lancedb.connect_async() for async.
LanceModel (schema)
✓ from lancedb.pydantic import LanceModel, Vector
✗ from pydantic import BaseModel
LanceDB schemas require LanceModel, not plain pydantic BaseModel. Vector field uses lancedb's Vector type.
No server needed. Data is stored on disk as Lance files. create_index() is required for ANN performance — without it, all searches are exact (brute-force). Versioning is automatic: every add/delete creates a new version.
import lancedb
import numpy as np
from lancedb.pydantic import LanceModel, Vector
# Connect (creates directory if not exists)
db = lancedb.connect("/tmp/my-lancedb")
# Define schema using LanceModel
class Item(LanceModel):
text: str
vector: Vector(128) # fixed dimensions
# Create table
table = db.create_table("items", schema=Item, mode="overwrite")
# Add data
data = [
Item(text="hello world", vector=np.random.rand(128).astype('float32'))
for _ in range(100)
]
table.add(data)
# Vector search (returns pandas DataFrame by default)
query_vec = np.random.rand(128).astype('float32')
results = table.search(query_vec).limit(5).to_pandas()
print(results)
# Create ANN index (required for scale)
table.create_index(metric="cosine") # IVF_PQ by default
Debug
Known issues
breakingIllegal instruction (SIGILL) crash on import on older Intel CPUs (pre-AVX2). lancedb/pylance wheels are compiled with AVX2 SIMD instructions. Affects Ubuntu 20.04 on older hardware and some VMs where CPU features are masked.fixRequires AVX2-capable CPU. Check with: grep avx2 /proc/cpuinfo. No workaround via pip — must use newer hardware or build from source without AVX2.
affects: all
breakingSome lancedb releases have pinned a pre-release version of pylance as a hard dependency (e.g., lancedb==0.17.1 required pylance==0.21.0b5). This breaks pip/uv installs in strict environments that disallow pre-release packages.fixIf a version fails to resolve, pin to the previous minor version or add --prerelease=allow to uv. Check GitHub releases for known bad versions.
affects: specific patch versions (0.17.1 documented, others possible)
breakingPython >=3.10 required as of lancedb 0.25+. Earlier Python versions raise install or import errors.fixUse Python 3.10, 3.11, 3.12, or 3.13.
affects: 0.25.0+
gotchaPyPI status is 'Development Status :: 3 - Alpha' despite being widely used in production. The API has had breaking changes between minor versions. Pin lancedb to a specific version in production.fixPin in requirements: lancedb==0.29.2. Review CHANGELOG before upgrading.
affects: all
gotchaANN index (create_index) must be created explicitly. Without it, all searches are O(n) brute-force regardless of dataset size. No warning is emitted — queries silently degrade at scale.fixCall table.create_index(metric='cosine') after loading data. For large datasets, tune num_partitions and num_sub_vectors for IVF_PQ.
affects: all
gotchaAutomatic versioning creates a new Lance snapshot on every write operation. On high-frequency write workloads this accumulates many small version files rapidly, increasing storage and compaction overhead.fixPeriodically run table.compact_files() and table.cleanup_old_versions() to manage storage. This is not done automatically.
affects: all
gotchapylance (the LanceDB dependency) is a completely different package from pylance (Microsoft's Python language server for VS Code). pip install pylance without context installs Microsoft's package. lancedb's pylance is only installed as a transitive dependency.fixNever manually pip install pylance expecting lancedb's version. It is pulled in automatically by lancedb.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'lance.vector'
This error occurs when the underlying `lance` or `pylance` dependency, which `lancedb` relies on for its core functionality, is not correctly installed or accessible in your Python environment, often due to dependency conflicts or specific `lancedb` versions.
fixEnsure `lancedb` and its dependencies are properly installed. It is recommended to use a fresh virtual environment and reinstall `lancedb` with `pip install lancedb`. If the issue persists, check your `pylance` installation.
ImportError: cannot import name 'LanceDb' from 'lancedb'
Developers are attempting to import a class named 'LanceDb', which does not exist in the `lancedb` library's top-level module. The correct way to establish a database connection is by calling `lancedb.connect()`.
fixInstead of `from lancedb import LanceDb`, use `import lancedb` and then connect using `db = lancedb.connect("path/to/db")`. AttributeError: 'pyarrow.lib.DataType' object has no attribute 'value_field'
This `AttributeError` indicates an incompatibility between the installed version of `lancedb` and `pyarrow`. `lancedb` depends on specific `pyarrow` features, and if your `pyarrow` version is too old or too new, this error can arise.
fixUpgrade both `lancedb` and `pyarrow` to their latest compatible versions using `pip install --upgrade lancedb pyarrow`. If issues persist, refer to LanceDB's documentation for specific `pyarrow` version requirements.
RuntimeError: lance error: LanceError(Arrow): Arrow error: C Data interface error: Unknown error: 'pyarrow.lib.RecordBatch' object has no attribute 'set_column'. Detail: Python exception: AttributeError.
This error happens when `lancedb` tries to use a method (`set_column`) on `pyarrow.lib.RecordBatch` that is not available in the installed `pyarrow` version, typically occurring with `pyarrow` versions older than 16.0.0.
fixUpgrade your `pyarrow` library to version `16.0.0` or newer by running `pip install --upgrade "pyarrow>=16.0.0"`.
Upgrade
Version history
0.37.1latest on PyPI · released Aug 10, 2026
Audit
Dependencies
pyarrowrequiredRequired. All data is represented as PyArrow tables. Vectors are stored as fixed-size list arrays.
pylancerequiredRequired. The Lance format Rust library (Python bindings). NOT Microsoft's Python language server — different package despite the same name.
numpyrequiredRequired for vector operations.
pydanticrequiredRequired for schema definitions.