Weaviate Python Client

4.20.0 · active · verified Sat Feb 28

Official Python client for the Weaviate vector database. v4 is a complete rewrite from v3 — uses gRPC for data operations (significantly faster), strong typing, collection-centric API, and context manager connection lifecycle. v3 API (weaviate.Client class) removed from the v4 package as of late 2024. Compatible with Weaviate server >= 1.23.7. Supports local, cloud (Weaviate Cloud), and custom deployments.

Warnings

breaking weaviate.Client() (v3 API) removed from weaviate-client >= 4.0.0 as of late 2024. Raises AttributeError. Enormous volume of tutorials, LangChain/LlamaIndex integration docs, and LLM-generated code uses v3 patterns.
Fix: Migrate to v4 API: replace weaviate.Client() with weaviate.connect_to_local() / connect_to_weaviate_cloud() / connect_to_custom(). Full migration guide: docs.weaviate.io/weaviate/client-libraries/python/v3_v4_migration. Or pin: pip install 'weaviate-client>=3.26.7,<4.0.0' — but v3 receives no new features.
breaking v4 client requires Weaviate server >= 1.23.7. v4.9+ aligns with Weaviate >= 1.27. Connecting v4 client to older servers raises gRPC errors or returns unexpected API responses.
Fix: Upgrade Weaviate server first. Check compatibility matrix in the release notes. Client minor versions track server minor versions (e.g., client 4.9.x pairs with server 1.27.x).
breaking gRPC port 50051 must be open to Weaviate server. v4 client uses gRPC for all data operations. Docker deployments that only expose port 8080 (HTTP) fail with WeaviateGRPCUnavailableError on any query/insert.
Fix: Add port mapping 50051:50051 to docker-compose.yml. For connect_to_custom(), specify both http_host/http_port and grpc_host/grpc_port explicitly.
breaking Configure.NamedVectors renamed to Configure.Vectors in v4.16.0. Configure.Vectorizer.none() renamed to Configure.Vectors.self_provided(). Code written against 4.15.x and earlier breaks on upgrade.
Fix: Replace Configure.NamedVectors.* with Configure.Vectors.* and Configure.MultiVectors.* for multi-vector configurations. Replace Configure.Vectorizer.none() with Configure.Vectors.self_provided().
breaking OIDC authentication for Weaviate Cloud deprecated in v4.16+, removed in early August 2025. Raises deprecation warning then AuthenticationFailedError.
Fix: Switch to API key authentication: Auth.api_key('your-api-key') passed to auth_credentials in connect_to_weaviate_cloud().
gotcha v4 client must be used as a context manager (with weaviate.connect_to_local() as client:) or client.close() must be called explicitly. Failing to close leaks gRPC connections and eventually causes channel exhaustion.
Fix: Always use context manager pattern or call client.close() in a finally block. Do not instantiate WeaviateClient at module level without explicit lifecycle management.
gotcha collections.get() is deprecated in 4.18.0 and will be removed. New code should use collections.use() which is an exact functional equivalent introduced as the preferred alias.
Fix: Replace client.collections.get('Name') with client.collections.use('Name') in all new code.

Install

pip install weaviate-client Standard install
pip install 'weaviate-client[agents]' With Weaviate Agents support (4.18+)
pip install 'weaviate-client>=3.26.7,<4.0.0' Pin to v3 if migrating gradually (no new features)

Imports

connect_to_local / connect_to_weaviate_cloud / WeaviateClient
```
import weaviate
client = weaviate.connect_to_local()  # local
client = weaviate.connect_to_weaviate_cloud(cluster_url=..., auth_credentials=...)  # cloud
```
weaviate.Client() is the v3 API, removed from weaviate-client >= 4.0. Raises AttributeError on current installs. v3 client still importable via weaviate-client>=3.26.7,<4.0.0.
collections.use (preferred) vs collections.get (deprecated)
```
collection = client.collections.use('MyCollection')
```
collections.get() is deprecated as of v4.18.0 and will be removed. Use collections.use() instead. Both currently work but get() emits a deprecation warning.
Configure.Vectors (new) vs Configure.NamedVectors (removed)
```
from weaviate.classes.config import Configure
Configure.Vectors.text2vec_openai()
```
Configure.NamedVectors replaced by Configure.Vectors and Configure.MultiVectors in v4.16.0. Configure.Vectorizer.none() replaced by Configure.Vectors.self_provided().

Quickstart

v4 uses context manager (with ... as client) to manage connection lifecycle. collections.use() is the preferred method (collections.get() deprecated in 4.18).

import weaviate
from weaviate.classes.init import Auth

# Local Weaviate instance
with weaviate.connect_to_local() as client:
    # Create or get collection
    if not client.collections.exists('Documents'):
        client.collections.create('Documents')

    collection = client.collections.use('Documents')

    # Insert object
    uuid = collection.data.insert({'text': 'Hello world', 'source': 'test'})

    # Query
    results = collection.query.near_text(query='hello', limit=5)
    for obj in results.objects:
        print(obj.properties)

view raw JSON →