pymilvus

library3.0.1pypypi✓ verified 26d ago

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.

vector-search database

pip install pymilvus

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PYMILVUS

pymilvus

vector-searchpythonv3.0.1

Install

12.5s avg

Import

2200ms

Disk

528MB

Pass rate

9/ 10

Env Coverage9 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ 0.03s

✓ 18.93s

py 3.11

✓ —

✓ 16.17s

py 3.12

✓ 0.03s

✓ 15.67s

py 3.13

2/3 runs

✓ 16.1s

py 3.9

✓ —

✓ 20.8s

528MB installed

● package 528MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MilvusClient

✓ from pymilvus import MilvusClient

✗ from pymilvus import MilvusClient

Collection

✓ from pymilvus import Collection

Connections

✓ from pymilvus import Connections

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)

Debug

Known issues

breakingPyMilvus 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.

affects: all

breakingMilvus 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.

affects: all

breakingORM 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.

affects: all

gotchaMilvusClient 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.

affects: ~2.5.4

gotchaCollections 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.

affects: all

gotchapymilvus[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.

affects: all

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

affects: all

breakingInstalling 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++`.

affects: all

Upgrade

Version history

3.0.1latest on PyPI · released Jul 29, 2026

Audit

Dependencies

grpciorequiredRequired. All Milvus connections use gRPC. Port 19530 must be open to server.

milvus-liteoptionalOptional. Embedded SQLite-backed local mode. Linux and macOS only — Windows not supported.

Agent activity

111 hits · last 30 days

node

102

OpenAI (training)

Resources

githubhttps://github.com/milvus-io/pymilvus ↗

packagehttps://pypi.org/project/pymilvus/ ↗

homepagehttps://milvus.io ↗