Redis Vector / RedisVL

0.14.1 verified Tue May 12 auth: no python install: stale quickstart: stale

The official AI-native Python client for vector search on Redis. Wraps redis-py with a high-level interface for defining vector schemas, building HNSW/FLAT indexes, running hybrid search, semantic routing, LLM caching, and session memory. Requires Redis 7.2+ with Search & Query module, or Redis Stack (self-hosted), or Redis Cloud. The underlying redis-py client is a separate package ('redis') — redisvl depends on it. Import root is 'redisvl'. Maintained by Redis Inc.

pip install redisvl

Common errors

error redis.exceptions.ResponseError: unknown command 'FT.CREATE' ↓

cause 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.

fix

Ensure 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.

error ImportError: cannot import name 'RedisVectorStore' from 'redisvl' ↓

cause 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.

fix

If 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).

error TypeError: __init__ missing 1 required positional argument: 'dims' ↓

cause 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.

fix

Provide the dims argument when creating VectorField, e.g., VectorField(name='vector', dims=1536).

Warnings

breaking Plain 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. ↓

fix Use: docker run -d redis/redis-stack:latest for local dev, or Redis Cloud free tier. Cannot use standard redis:latest Docker image.

breaking HybridQuery (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. ↓

fix Check Redis version before using HybridQuery. Use AggregateHybridQuery for Redis < 8.4.0.

breaking redis-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. ↓

fix Pin dialect explicitly in queries if you need dialect 1 behavior, or audit query results after upgrading redis-py to 6.x.

gotcha COSINE 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. ↓

fix Use 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.

gotcha Vectors 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. ↓

fix Always call .astype('float32').tobytes() when using HASH storage. JSON storage type handles serialization differently — check redisvl docs for your storage_type.

gotcha redisvl 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. ↓

fix Keep redisvl up to date. If hitting ImportError on botocore, upgrade redisvl.

breaking Building '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. ↓

fix Install C++ build essentials before installing redisvl. For Alpine, use `apk add build-base python3-dev`.

Install

pip install redisvl[openai]

pip install redisvl[all]

pip install redisvl[hiredis]

docker run -d --name redis -p 6379:6379 -p 8001:8001 redis/redis-stack:latest

Install compatibility stale last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) redisvl - - - -

3.10 alpine (musl) all - - - -

3.10 alpine (musl) hiredis - - - -

3.10 alpine (musl) openai - - - -

3.10 slim (glibc) redisvl - - 0.57s 128M

3.10 slim (glibc) all - - 0.59s 128M

3.10 slim (glibc) hiredis - - 0.58s 128M

3.10 slim (glibc) openai - - 0.57s 147M

3.11 alpine (musl) redisvl - - - -

3.11 alpine (musl) all - - - -

3.11 alpine (musl) hiredis - - - -

3.11 alpine (musl) openai - - - -

3.11 slim (glibc) redisvl - - 1.01s 137M

3.11 slim (glibc) all - - 1.09s 137M

3.11 slim (glibc) hiredis - - 1.06s 137M

3.11 slim (glibc) openai - - 1.02s 157M

3.12 alpine (musl) redisvl - - - -

3.12 alpine (musl) all - - - -

3.12 alpine (musl) hiredis - - - -

3.12 alpine (musl) openai - - - -

3.12 slim (glibc) redisvl - - 1.27s 125M

3.12 slim (glibc) all - - 1.20s 125M

3.12 slim (glibc) hiredis - - 1.24s 125M

3.12 slim (glibc) openai - - 1.25s 145M

3.13 alpine (musl) redisvl - - - -

3.13 alpine (musl) all - - - -

3.13 alpine (musl) hiredis - - - -

3.13 alpine (musl) openai - - - -

3.13 slim (glibc) redisvl - - 1.20s 124M

3.13 slim (glibc) all - - 1.12s 124M

3.13 slim (glibc) hiredis - - 1.20s 124M

3.13 slim (glibc) openai - - 1.15s 144M

3.9 alpine (musl) redisvl - - - -

3.9 alpine (musl) all - - - -

3.9 alpine (musl) hiredis - - - -

3.9 alpine (musl) openai - - - -

3.9 slim (glibc) redisvl - - 0.70s 138M

3.9 slim (glibc) all - - 0.70s 138M

3.9 slim (glibc) hiredis - - 0.69s 138M

3.9 slim (glibc) openai - - 0.70s 156M

Imports

SearchIndex
wrong
```
import redisvl
```
correct
```
from redisvl.index import SearchIndex
```
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.

Quickstart stale last tested: 2026-05-12

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)