Weaviate Python Client
raw JSON → 4.20.0 verified Tue May 12 auth: no python install: verified quickstart: stale
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.
pip install weaviate-client Common errors
error ModuleNotFoundError: No module named 'weaviate.Client' ↓
cause The `Client` class was the main entry point for `weaviate-client` v3. In v4, the main client class is `WeaviateClient` and its import path has changed.
fix
from weaviate import WeaviateClient
error AttributeError: 'WeaviateClient' object has no attribute 'data_object' ↓
cause The `data_object` attribute for CRUD operations was used in the v3 client. In v4, data operations are performed through the `data` attribute of a specific `Collection` object.
fix
client.collections.get('CollectionName').data.insert(properties={...})
error AttributeError: 'WeaviateClient' object has no attribute 'query' ↓
cause The `query` attribute for GraphQL queries was used in the v3 client. In v4, querying is performed through the `query` attribute of a specific `Collection` object.
fix
client.collections.get('CollectionName').query.fetch_objects()
error TypeError: WeaviateClient.__init__ got an unexpected keyword argument 'auth_client_secret' ↓
cause The `WeaviateClient` constructor in v4 expects an `AuthCredentials` object (e.g., `AuthApiKey`) for authentication, not a raw string API key.
fix
from weaviate.auth import AuthApiKey
client = WeaviateClient(..., auth_client_secret=AuthApiKey('YOUR_API_KEY'))
error GRPC connection error: 14 UNAVAILABLE: failed to connect to all addresses ↓
cause The Weaviate server is not running, is unreachable, or there is a network/firewall issue preventing the client from establishing a gRPC connection.
fix
Ensure the Weaviate server is running and accessible at the URL specified in
client.WeaviateClient(url='...', ...). Check network connectivity and firewall rules. 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[agents]' pip install 'weaviate-client>=3.26.7,<4.0.0' Install compatibility verified last tested: 2026-05-12
python os / libc variant status wheel install import disk
3.10 alpine (musl) 'weaviate-client>=3.26.7,<4.0.0' - - 1.07s 41.1M
3.10 alpine (musl) agents - - 3.77s 92.6M
3.10 alpine (musl) weaviate-client - - 3.28s 79.6M
3.10 slim (glibc) 'weaviate-client>=3.26.7,<4.0.0' - - 0.78s 41M
3.10 slim (glibc) agents - - 2.48s 90M
3.10 slim (glibc) weaviate-client - - 1.89s 77M
3.11 alpine (musl) 'weaviate-client>=3.26.7,<4.0.0' - - 1.56s 43.8M
3.11 alpine (musl) agents - - 5.20s 99.4M
3.11 alpine (musl) weaviate-client - - 4.55s 85.1M
3.11 slim (glibc) 'weaviate-client>=3.26.7,<4.0.0' - - 1.26s 44M
3.11 slim (glibc) agents - - 3.39s 96M
3.11 slim (glibc) weaviate-client - - 2.83s 82M
3.12 alpine (musl) 'weaviate-client>=3.26.7,<4.0.0' - - 1.29s 35.4M
3.12 alpine (musl) agents - - 4.39s 90.1M
3.12 alpine (musl) weaviate-client - - 3.88s 76.1M
3.12 slim (glibc) 'weaviate-client>=3.26.7,<4.0.0' - - 1.32s 36M
3.12 slim (glibc) agents - - 3.66s 87M
3.12 slim (glibc) weaviate-client - - 3.04s 73M
3.13 alpine (musl) 'weaviate-client>=3.26.7,<4.0.0' - - 1.26s 35.0M
3.13 alpine (musl) agents - - 4.14s 89.8M
3.13 alpine (musl) weaviate-client - - 3.66s 75.7M
3.13 slim (glibc) 'weaviate-client>=3.26.7,<4.0.0' - - 1.28s 35M
3.13 slim (glibc) agents - - 3.48s 87M
3.13 slim (glibc) weaviate-client - - 3.00s 73M
3.9 alpine (musl) 'weaviate-client>=3.26.7,<4.0.0' - - 1.00s 41.2M
3.9 alpine (musl) agents - - 3.67s 92.2M
3.9 alpine (musl) weaviate-client - - 3.10s 79.4M
3.9 slim (glibc) 'weaviate-client>=3.26.7,<4.0.0' - - 0.89s 42M
3.9 slim (glibc) agents - - 2.71s 89M
3.9 slim (glibc) weaviate-client - - 2.21s 76M
Imports
- connect_to_local / connect_to_weaviate_cloud / WeaviateClient wrong
import weaviate client = weaviate.Client('http://localhost:8080')correctimport weaviate client = weaviate.connect_to_local() # local client = weaviate.connect_to_weaviate_cloud(cluster_url=..., auth_credentials=...) # cloud - collections.use (preferred) vs collections.get (deprecated) wrong
collection = client.collections.get('MyCollection')correctcollection = client.collections.use('MyCollection') - Configure.Vectors (new) vs Configure.NamedVectors (removed) wrong
Configure.NamedVectors.text2vec_openai()correctfrom weaviate.classes.config import Configure Configure.Vectors.text2vec_openai()
Quickstart stale last tested: 2026-05-12
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)