Install & Compatibility
Where this runs
tested against v0.1.78 · 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
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.4s · import 0.462s · 147MB
155MB installed
● package 155MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
tensorstore
✓ import tensorstore as ts
This example demonstrates creating a new N5 dataset on the local filesystem, writing a small NumPy array to a sub-region, and then reading back a larger region. It highlights the asynchronous nature of TensorStore operations, requiring `.result()` or `await` to wait for completion.
import tensorstore as ts
import numpy as np
import os
# Define a temporary directory for local storage
output_dir = 'tmp_tensorstore_dataset'
# Create a new N5 dataset on the local filesystem
dataset = ts.open({
'driver': 'n5',
'kvstore': {
'driver': 'file',
'path': output_dir,
},
'metadata': {
'compression': {'type': 'gzip'},
'dataType': 'uint32',
'dimensions': [1000, 20000],
'blockSize': [100, 100],
},
'create': True,
'delete_existing': True,
}).result()
# Asynchronously write to a sub-region
write_future = dataset[80:82, 99:102].write(np.array([[1, 2, 3], [4, 5, 6]], dtype=np.uint32))
# Wait for the write to complete
write_future.result()
# Read back a larger region
read_data = dataset[80:83, 99:102].read().result()
print(f"Data written to {output_dir}")
print(f"Read data:\n{read_data}")
# Clean up the temporary directory
import shutil
shutil.rmtree(output_dir)
print(f"Cleaned up {output_dir}")
Debug
Known issues
breakingTensorStore requires Python 3.11 or later. Users attempting to install or run it with older Python versions (e.g., 3.10 or below) will encounter installation failures or runtime errors.fixUpgrade Python to version 3.11 or newer.
affects: <0.1.82 (Python < 3.11)
gotchaTensorStore's Python API is heavily asynchronous. Most I/O operations return `tensorstore.Future` objects. Failing to explicitly call `.result()` on these futures (or `await` them in an `async` context) will result in operations not completing or data not being available as expected.fixAlways append `.result()` to asynchronous calls (e.g., `ts.open(...).result()`, `dataset.write(...).result()`) or use `await` within `async` functions.
affects: All versions
gotchaWhen using cloud storage drivers (e.g., Google Cloud Storage, Amazon S3), proper authentication credentials must be configured in your environment. Operations will fail with permission errors if credentials are missing or incorrect.fixEnsure your environment is authenticated with the respective cloud provider (e.g., `gcloud auth application-default login` for GCS, AWS credentials for S3).
affects: All versions
gotchaBuilding TensorStore from source (instead of using pre-built PyPI wheels) requires specific C++ compilers (e.g., GCC 10+, Clang 8+, MSVC 2022+) and the Bazel build system. On Windows, long path names can lead to compilation errors like `fatal error C1083: Cannot open include file`.fixPrefer pre-built wheels (`pip install tensorstore`). If building from source on Windows, configure Bazel to use a shorter output base path (e.g., `TENSORSTORE_BAZEL_STARTUP_OPTIONS="--output_base=C:\\Out"`).
affects: All versions (when building from source)
Errors
Common errors & fixes
error: Microsoft Visual C++ 14.0 or greater is required.
Building the tensorstore Python package from source on Windows requires the Microsoft Visual C++ Build Tools.
fixInstall the C++ build tools for Visual Studio via the Visual Studio Installer, or download the Build Tools for Visual Studio.
Error opening TensorStore: Storage driver 'invalid_driver_name' not found.
The specified 'driver' in `tensorstore.open()` does not correspond to a known or valid TensorStore storage driver.
fixUse one of the supported storage drivers such as 'zarr', 'n5', 'neuroglancer_precomputed', 'file', or 'array'.
AttributeError: 'Future' object has no attribute 'shape'
An asynchronous TensorStore operation (like `ts.open()`, `ts.read()`, `ts.write()`) was called but its returned `Future` object was not awaited, and a subsequent array operation was attempted directly on the `Future` instead of the resolved array.
fixEnsure asynchronous operations are awaited using `await` in an `async` function, or explicitly call `.result()` on the `Future` object in a synchronous context (e.g., `arr = await ts.open(...)` or `arr = ts.open(...).result()`).
ValueError: Cannot convert numpy.dtype('float64') to tensorstore.dtype('int32')
Attempting to write data with an incompatible NumPy data type to a TensorStore array that was opened or created with a different, non-convertible dtype.
fixEnsure the data being written has a compatible NumPy dtype, or explicitly convert it using `.astype()` before writing. When creating a new array, specify the desired `dtype` in the spec.
Upgrade
Version history
0.1.85latest on PyPI · released Aug 5, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.11 or later.
numpyoptionalTypically used for array manipulation with TensorStore objects.