PyMilvus

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

Official Python SDK for Milvus, the open-source vector database. Has two coexisting APIs: the modern MilvusClient (recommended, introduced in 2.3) and the legacy ORM API (connections.connect + Collection class). Both currently work but LLM-generated and tutorial code overwhelmingly uses the old ORM patterns. Milvus Lite (embedded SQLite-based local mode) is available via the milvus-lite extra on Linux/macOS only. Server version must be kept in sync with client minor version.

pip install pymilvus

Common errors

error this version of sdk is incompatible with server, please downgrade your sdk or upgrade your server ↓

cause The `pymilvus` client library version is not compatible with the running Milvus server version. Milvus requires that the client and server minor versions (e.g., 2.3.x client with 2.3.y server) must match.

fix

Check both your pymilvus client version (pip show pymilvus) and your Milvus server version. Then, either upgrade your Milvus server or downgrade/upgrade your pymilvus client to a compatible version (e.g., pip install pymilvus==2.6.8).

error pymilvus.exceptions.MilvusException: <MilvusException: (code=2, message=Fail connecting to server on localhost:19530, illegal connection params or server unavailable)> ↓

cause The `pymilvus` client failed to establish a connection with the Milvus server. This often happens if the Milvus server is not running, is running on a different host/port, or network issues (like firewall or proxy) are preventing the connection.

fix

Ensure the Milvus server is running and accessible from where your Python script is executed. Verify the host and port in your connection string (e.g., MilvusClient('localhost:19530') or connections.connect(host='localhost', port='19530')) match your Milvus server's configuration. Check firewall settings and disable any interfering proxy settings if applicable.

error ModuleNotFoundError: No module named 'pymilvus' ↓

cause The `pymilvus` library is not installed in the Python environment you are currently using, or the Python interpreter cannot find it.

fix

Install pymilvus using pip: pip install pymilvus. If you are using a virtual environment, ensure it is activated before installation. If the error persists, check your PYTHONPATH or verify that the correct Python interpreter is being used.

error AttributeError: 'MilvusClient' object has no attribute 'create_collection_with_schema' ↓

cause You are attempting to use a method that either does not exist, has been renamed, or is part of a different API (e.g., the legacy ORM API vs. the modern `MilvusClient` API) in the `pymilvus` version you have installed. Specifically, `create_collection_with_schema` was an older method, replaced by `create_collection` with schema parameters.

fix

Consult the official pymilvus documentation for your installed version (2.6.8) to use the correct methods. For MilvusClient, create_collection_with_schema has been integrated into create_collection where schema can be passed as an argument. For example, instead of client.create_collection_with_schema(...), use client.create_collection(..., schema=your_schema).

error collection not loaded ↓

cause Operations like search or query require a Milvus collection to be loaded into memory. This error indicates that the collection you are trying to operate on has not been loaded or the loading process failed.

fix

After creating or getting a collection object, explicitly load it into memory before performing search or query operations. For the ORM API, call collection.load(). For MilvusClient, use client.load_collection(collection_name='your_collection_name').

Warnings

breaking PyMilvus client version must match Milvus server minor version. pymilvus 2.6.x requires Milvus server 2.6.x. Using pymilvus 2.6 against a Milvus 2.4 server causes gRPC proto mismatch errors and silent data corruption. ↓

fix Always align client and server versions. Check compatibility table: milvus.io/docs/release_notes.md. When upgrading server, upgrade client simultaneously.

breaking Milvus Lite (.db file mode) is not available on Windows. MilvusClient('local.db') on Windows raises ModuleNotFoundError: No module named 'milvus_lite'. ↓

fix On Windows, run a Milvus server (Docker) and connect via uri=. There is no embedded mode for Windows.

breaking ORM API (Collection class) and MilvusClient are not fully interoperable. Collections created via Collection() may not appear in client.list_collections() due to internal state management differences. Mixing the two APIs in the same codebase causes hard-to-debug visibility issues. ↓

fix Use only one API style per codebase. Prefer MilvusClient for all new code. If migrating legacy ORM code, convert fully rather than mixing.

gotcha MilvusClient database= parameter does not reliably set the active database context in some versions (confirmed bug in 2.5.4). Collections may be created in the default database instead of the specified one. ↓

fix After connecting, explicitly call client.using_database('db_name') to ensure the correct database context is active.

gotcha Collections must be loaded into memory before search or query. client.search() on an unloaded collection returns empty results or raises a not-loaded error. Loading is asynchronous by default. ↓

fix Call client.load_collection('name') before searching. For async load: poll client.get_load_state('name') until state is LoadState.Loaded before issuing queries.

gotcha pymilvus[model] installs heavyweight ML dependencies (torch, transformers, sentence-transformers). pip install pymilvus[model] in a lean environment adds 1–2GB of packages. ↓

fix Only install [model] extra if you need local embedding generation. For production, generate embeddings separately and pass float vectors directly to insert/search.

gotcha zsh users: pip install pymilvus[model] fails with 'zsh: no matches found'. zsh treats square brackets as glob patterns. ↓

fix Quote the package spec: pip install 'pymilvus[model]'

breaking Installing PyMilvus on minimal Linux distributions (e.g., Alpine) or via specific source builds for dependencies like `grpcio` can fail with `FileNotFoundError: [Errno 2] No such file or directory: 'c++'` or similar compiler errors. This indicates missing system-level build tools required to compile Python packages with C/C++ extensions. ↓

fix Ensure that build essential packages are installed in your environment. For Alpine Linux, run `apk add build-base g++`. For Debian/Ubuntu, use `apt-get install build-essential`. For CentOS/RHEL, use `yum install gcc-c++` or `dnf install gcc-c++`.

Install

pip install 'pymilvus[model]'

pip install 'pymilvus[milvus-lite]'

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) milvus-lite - - - -

3.10 alpine (musl) model - - - -

3.10 alpine (musl) pymilvus - - 2.48s 193.9M

3.10 slim (glibc) milvus-lite - - 1.26s 354M

3.10 slim (glibc) model - - 1.25s 568M

3.10 slim (glibc) pymilvus - - 1.22s 184M

3.11 alpine (musl) milvus-lite - - - -

3.11 alpine (musl) model - - - -

3.11 alpine (musl) pymilvus - - 3.29s 208.2M

3.11 slim (glibc) milvus-lite - - 1.94s 368M

3.11 slim (glibc) model - - 1.86s 558M

3.11 slim (glibc) pymilvus - - 1.90s 197M

3.12 alpine (musl) milvus-lite - - - -

3.12 alpine (musl) model - - - -

3.12 alpine (musl) pymilvus - - 3.10s 202.0M

3.12 slim (glibc) milvus-lite - - 2.23s 362M

3.12 slim (glibc) model - - 2.16s 545M

3.12 slim (glibc) pymilvus - - 2.17s 191M

3.13 alpine (musl) milvus-lite - - - -

3.13 alpine (musl) model - - - -

3.13 alpine (musl) pymilvus - - 2.91s 200.9M

3.13 slim (glibc) milvus-lite - - 2.17s 360M

3.13 slim (glibc) model - - 2.14s 543M

3.13 slim (glibc) pymilvus - - 2.15s 190M

3.9 alpine (musl) milvus-lite - - - -

3.9 alpine (musl) model - - - -

3.9 alpine (musl) pymilvus - - 2.36s 201.5M

3.9 slim (glibc) milvus-lite - - 1.46s 364M

3.9 slim (glibc) model - - 1.42s 562M

3.9 slim (glibc) pymilvus - - 1.43s 194M

Imports

MilvusClient (recommended)
wrong
```
from pymilvus import connections, Collection
connections.connect('default', host='localhost', port='19530')
col = Collection('my_collection')
```
correct
```
from pymilvus import MilvusClient
client = MilvusClient(uri='http://localhost:19530', token='root:Milvus')
# Milvus Lite (local, no server):
# client = MilvusClient('local.db')
```
ORM API (connections.connect + Collection) is the legacy pattern. Still works but all new Milvus documentation uses MilvusClient. LLMs and old tutorials almost exclusively generate ORM-style code. The two APIs are not interoperable — collections created via ORM Collection() are not visible to MilvusClient.list_collections() in some Milvus versions and vice versa.
MilvusClient uri (not host/port)
wrong
```
client = MilvusClient(host='localhost', port=19530)
```
correct
```
client = MilvusClient(uri='http://localhost:19530')
```
MilvusClient constructor takes uri= not host=/port=. Passing http= (a common mistake) silently fails — the parameter is not recognized and the client attempts a .db file path resolution.

Quickstart stale last tested: 2026-05-12

MilvusClient is the recommended API for all new code. Milvus Lite works for prototyping on Linux/macOS but is NOT available on Windows.

from pymilvus import MilvusClient, DataType

# Connect to running Milvus server
client = MilvusClient(uri='http://localhost:19530', token='root:Milvus')

# Milvus Lite (embedded, no server, Linux/macOS only):
# client = MilvusClient('my_data.db')

# Create collection (simple API)
client.create_collection(
    collection_name='docs',
    dimension=768,
)

# Insert
data = [
    {'id': 1, 'vector': [0.1] * 768, 'text': 'hello world'},
]
client.insert(collection_name='docs', data=data)

# Search
results = client.search(
    collection_name='docs',
    data=[[0.1] * 768],
    limit=5,
    output_fields=['text'],
)
print(results)