Install & Compatibility
Where this runs
tested against v0.26.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
py 3.10
✕ build_error
3/4 runs
py 3.11
✕ build_error
3/4 runs
py 3.12
✕ build_error
✓ 33.48s
py 3.13
✕ build_error
✓ 30.58s
py 3.9
✕ build_error
3/4 runs
5632MB installed
● package 5632MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SearchIndex
✓ from redisvl.index import SearchIndex
✗ import redisvl
redisvl does not have a useful top-level import. All classes are in submodules.
VectorQuery
✓ from redisvl.query import VectorQuery
Also HybridQuery (Redis 8.4.0+ only), RangeQuery, FilterQuery.
IndexSchema
✓ from redisvl.schema import IndexSchema
Schema can be loaded from a dict or YAML file.
Requires Redis Stack or Redis Cloud running locally. Vectors stored as bytes (float32.tobytes()) in HASH storage. HNSW index supports incremental inserts. Use AsyncSearchIndex for async workflows.
import numpy as np
from redis import Redis
from redisvl.index import SearchIndex
from redisvl.schema import IndexSchema
from redisvl.query import VectorQuery
# Define schema
schema = IndexSchema.from_dict({
"index": {"name": "docs", "prefix": "doc", "storage_type": "hash"},
"fields": [
{"name": "text", "type": "text"},
{
"name": "embedding",
"type": "vector",
"attrs": {
"algorithm": "hnsw",
"datatype": "float32",
"dims": 4,
"distance_metric": "cosine"
}
}
]
})
# Connect and create index
index = SearchIndex(schema, redis_url="redis://localhost:6379")
index.create(overwrite=True)
# Load data
index.load([
{"id": "1", "text": "hello world", "embedding": np.array([0.1, 0.2, 0.3, 0.4], dtype='float32').tobytes()},
])
# Search
query = VectorQuery(
vector=[0.1, 0.2, 0.3, 0.4],
vector_field_name="embedding",
num_results=5
)
results = index.query(query)
print(results)
redisvl --version
Debug
Known issues
breakingPlain redis (Redis OSS) does not support vector search. You must use Redis Stack, Redis Cloud, or Redis Enterprise — all of which include the Search & Query module. pip install redisvl succeeds but all index operations fail against plain Redis.fixUse: docker run -d redis/redis-stack:latest for local dev, or Redis Cloud free tier. Cannot use standard redis:latest Docker image.
affects: all
breakingHybridQuery (native hybrid text+vector search) requires Redis 8.4.0+. Using it against Redis 7.x or 8.x < 8.4.0 raises a command error. AggregateHybridQuery is the backward-compatible alternative.fixCheck Redis version before using HybridQuery. Use AggregateHybridQuery for Redis < 8.4.0.
affects: all
breakingredis-py 6.0.0 introduced a client-side default dialect override (DIALECT 2) for FT.SEARCH and FT.AGGREGATE. This can change query results compared to older versions. Affects raw redis-py users who rely on default dialect behavior.fixPin dialect explicitly in queries if you need dialect 1 behavior, or audit query results after upgrading redis-py to 6.x.
affects: redis>=6.0.0
gotchaCOSINE distance in Redis uses the range [0, 2], not [0, 1]. 0 = identical, 2 = opposite. Documentation has historically stated [0, 1] in some places — this was incorrect. Fixed in redisvl release notes.fixUse thresholds in [0, 2] range for cosine distance in Redis. A threshold of 0.2 in pinecone/other libraries is ~0.2 here too but verify against your data.
affects: all
gotchaVectors must be stored as bytes (np.array(..., dtype='float32').tobytes()) for HASH storage type. Passing a Python list or numpy array directly to index.load() silently stores wrong data.fixAlways call .astype('float32').tobytes() when using HASH storage. JSON storage type handles serialization differently — check redisvl docs for your storage_type. affects: all (HASH storage)
gotcharedisvl previously had an unintentional dependency on botocore (AWS SDK). Any environment without boto would get an ImportError on redisvl.utils.vectorize. Fixed in a patch release.fixKeep redisvl up to date. If hitting ImportError on botocore, upgrade redisvl.
affects: specific older patch versions
breakingBuilding 'ml-dtypes' (a dependency of redisvl) on Alpine or other minimal environments fails due to missing C++ build tools (g++). This prevents redisvl from being installed.fixInstall C++ build essentials before installing redisvl. For Alpine, use `apk add build-base python3-dev`.
affects: all (on Alpine/minimal environments)
Errors
Common errors & fixes
redis.exceptions.ResponseError: unknown command 'FT.CREATE'
The connected Redis server does not have the Redis Search & Query module loaded or its version is older than 7.2, which is required by redisvl.
fixEnsure your Redis server is Redis Stack (which includes Redis Search) or Redis 7.2+ with the Search module explicitly loaded. For Docker, use `redis/redis-stack-server`.
ImportError: cannot import name 'RedisVectorStore' from 'redisvl'
The `RedisVectorStore` class is part of the `langchain-community` library's Redis integration, not the core `redisvl` client library. The main client for `redisvl` is the `RedisVL` class.
fixIf you intend to use `redisvl` as a standalone client, import `RedisVL`: `from redisvl.redisvl import RedisVL`. If you need the Langchain integration, use `from langchain_community.vectorstores import RedisVectorStore` (after `pip install langchain-community`).
TypeError: __init__ missing 1 required positional argument: 'dims'
When defining a `VectorField` in the `redisvl` schema, the `dims` parameter, which specifies the length of the embedding vectors, is a mandatory argument and has not been provided.
fixProvide the `dims` argument when creating `VectorField`, e.g., `VectorField(name='vector', dims=1536)`.
Upgrade
Version history
0.26.0latest on PyPI · released Aug 19, 2026
Audit
Dependencies
redisrequiredRequired. The underlying redis-py client. redisvl requires redis>=7.x (redis-py package). redis-py 7.x dropped Python 3.9 support — requires Python 3.10+.
numpyrequiredRequired. Vectors are passed as numpy float32 arrays internally.
pydanticrequiredRequired. Schema definitions use Pydantic models.