PyMilvus

2.6.8 · active · verified Sat Feb 28

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.

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]'

Install

pip install pymilvus Base SDK
pip install 'pymilvus[model]' With embedding/reranker model support
pip install 'pymilvus[milvus-lite]' With Milvus Lite (local embedded mode, Linux/macOS only)

Imports

MilvusClient (recommended)
```
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)
```
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

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)

view raw JSON →