Skip to main content

v3 to v4 migration guide

Python client version

The current Python client version is v4.5.0

The v4 Weaviate Python client API is very different to the v3 API. This guide will help you understand the major changes and how to migrate your code at a high level.


To go from v3 to v4, you must

  1. Upgrade the client library:

    pip install -U weaviate-client  # For beta versions: `pip install --pre -U "weaviate-client==4.*"`
  2. Upgrade Weaviate to a compatible version

    • Weaviate 1.23.7 is required for v4.4.1. Generally, we recommend you use the latest versions of Weaviate and the client.
  3. Make sure a port for gRPC is open to Weaviate.

    • The default port is 50051.
    docker-compose.yml example

    If you are running Weaviate with Docker, you can map the default port (50051) by adding the following to your docker-compose.yml file:

    - 8080:8080
    - 50051:50051


The v4 client is instantiated through the WeaviateClient object, which is the main entry point for all API operations.

You can directly instantiate the client, but in most cases you can use helper functions starting with _connect_to, such as connect_to_local, connect_to_wcs.

import weaviate
import os

client = weaviate.connect_to_wcs(
cluster_url=os.getenv("WCS_DEMO_URL"), # Replace with your WCS URL
auth_credentials=weaviate.auth.AuthApiKey(os.getenv("WCS_DEMO_RO_KEY")) # Replace with your WCS key

Once it has been instantiated, you will notice that the client API is different from v3.

Major changes

From a user's perspective, major changes with the v4 client include:

  • Extensive use of helper classes
  • Interaction with collections
  • Removal of builder patterns

Helper classes

The v4 client introduces an extensive set of helper classes to interact with Weaviate. These classes are used to provide strong typing, and to make the client more user-friendly such as through IDE autocompletion.

Take a look at the examples below.

import weaviate
import weaviate.classes.config as wvcc

client = weaviate.connect_to_local()

collection = client.collections.create(


In both of these examples, you can see how the helper classes and methods abstract away the need for manual JSONs or strings.

Interaction with collections

Interacting with the client object for CRUD and search operations have been replaced with the use of collection objects.

This conveniently removes the need to specify the collection for each operation, and reduces potential for errors.

    jeopardy = client.collections.get("JeopardyQuestion")

data_object = jeopardy.query.fetch_object_by_id("00ff6900-e64f-5d94-90db-c8cfa3fc851b")


Note here that the collection object can be re-used throughout the codebase.

Removal of builder patterns

The builder patterns for constructing queries as been removed, as they could be confusing and potentially lead to invalid queries.

In v4, queries are constructed using specific methods and its parameters.

    import weaviate.classes as wvc

jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.near_text(
query="animals in movies",

for o in response.objects:

This makes it easier to understand and use. Additionally, some parameters typed (e.g. MetadataQuery) which makes it easier to use and reduces errors.

How to migrate your code

The migration will likely involve significant changes to your codebase. Review the Python client library documentation to get started, including instantiation details and various submodules.

Then, take a look at the how-to guides for Managing data and Queries.

In particular, check out the pages for:

Can we help?

If you have any questions, please don't hesitate to reach out to us on the Weaviate Community Forum.