qdrant-client: the Python SDK for Qdrant, from local mode to cloud inference
Python client for Qdrant vector search engine
At a glance
- What is it?
- qdrant-client is the official Python client for the Qdrant vector search engine. It ships type hints for the full API, an in-process local mode, REST and gRPC transports, and an optional FastEmbed integration for embeddings.
- Who is it for?
- Adopt qdrant-client if you already run Qdrant or want to prototype vector search in a notebook without a server, since local mode and server mode share one API. Skip it if your stack is not Python or if you want the engine's behaviour to be independent of client version, because the client carries its own release cadence and the Qdrant API surface is versioned alongside it.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What qdrant-client solves and who it is for
Qdrant exposes a REST and gRPC API. Calling that API by hand means constructing request bodies, handling pagination on scroll, and keeping request and response shapes in sync with the server. qdrant-client packages those calls as typed Python methods, so a collection creation is a function call with a VectorParams argument rather than a JSON dict.
The intended audience is Python developers building retrieval features: semantic search over documents, recommendation, or any workload where similarity is computed on vectors. The README positions the library as type definitions for the whole Qdrant API plus helper methods for frequent operations, and it names collection upload as one of those helpers. The project is Apache-2.0 licensed, with the version in pyproject.toml listed as 1.19.0.
Local mode: the same API without a running server
The distinguishing feature compared with a thin HTTP wrapper is local mode. The README gives this example, and it is the one worth reading closely: you initialize the client against an in-memory store or a filesystem path, and the same method calls that would hit a server execute against a local implementation.
from qdrant_client import QdrantClient
client = QdrantClient(":memory:")
# or
client = QdrantClient(path="path/to/db") # Persists changes to diskAccording to the README, local mode is intended for development, prototyping and testing, including running tests in a CI pipeline and working in Colab or Jupyter without extra dependencies. The trade-off is explicit in the documentation's own framing: local mode covers the API surface the client implements locally, and the README's advice is to switch to server mode when you need to scale. That is a migration, not a configuration change, and it is the point where behaviour can diverge.
The path form persists to disk, and the client depends on portalocker (pinned as >=2.7.0,<4.0 in pyproject.toml), which is consistent with file-level locking on a local store. A single process holding that path is the safe assumption.
Installing qdrant-client and running a first search
Installation is a single pip command, as stated in the README:
pip install qdrant-clientTo connect to a server instead of local mode, the README shows host and port, or a URL. The documented port is 6333:
from qdrant_client import QdrantClient
client = QdrantClient(host="localhost", port=6333)
# or
client = QdrantClient(url="http://localhost:6333")If you do not have a server yet, the README gives a Docker one-liner for it:
docker run -p 6333:6333 qdrant/qdrant:latestA first real use is creating a collection and searching it. The README's example uses the models module for the distance and vector configuration:
from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams
client = QdrantClient(":memory:")
client.create_collection(
collection_name="my_collection",
vectors_config=VectorParams(size=100, distance=Distance.COSINE),
)The size must match the dimensionality of the vectors you later insert, and distance is a choice you cannot change after the fact without recreating the collection. The README's upload example imports PointStruct and numpy for inserting vectors; search is issued through query_points in the FastEmbed walkthrough, which returns an object whose .points attribute holds the results.
Inference API and the FastEmbed extra
The client can also produce embeddings, which removes a separate embedding step from the code path. Two modes exist. Local inference runs through FastEmbed, installed as an extra:
pip install qdrant-client[fastembed]FastEmbed, per the README, is based on ONNX Runtime and runs on CPU or GPU. The client then accepts models.Document objects in place of raw vectors, and get_embedding_size returns the dimensionality for the collection config. A GPU variant is installed separately with qdrant-client[fastembed-gpu], and the README states plainly that fastembed and fastembed-gpu are mutually exclusive: installing one after the other may require a fresh environment. Both are pinned to ^0.8 in pyproject.toml.
Remote inference is the second mode. The same API is used, but the client is constructed with cloud_inference=True against a Qdrant Cloud URL and API key. The README notes this is currently available only on paid plans, and that remote inference requires images as base64 encoded strings or urls. That last constraint matters if you were planning to pass raw file handles.
Where qdrant-client is the wrong tool
The clearest limitation is that this is a client, not a database. If you need a single process that owns both storage and query, local mode covers small prototyping workloads, but the README's own guidance is to move to server mode when scaling, which means running the Qdrant engine separately. Anyone expecting qdrant-client to be a self-contained embedded vector store for production traffic is reading it wrong.
A second constraint is the dependency floor. pyproject.toml requires Python >=3.10 and pins numpy differently per interpreter version, from >=1.21,<2.3.0 on 3.10 up to >=2.3.0 on 3.14. Environments locked to older numpy, or to Python 3.9, cannot install current releases. The pydantic requirement is also unusual: >=1.10.8 with exclusions for 2.0.*, 2.1.* and 2.2.0, which is a compatibility band rather than a clean minimum.
Third, the client does not insulate you from server version drift. The library tracks the Qdrant API, and a client release can expose methods an older server does not implement. The README points to api.qdrant.tech for the API surface but does not document a version compatibility matrix, so that check is left to the reader.
How it compares to other Python vector options
The nearest comparison is chromadb, which also offers an in-memory and persistent local mode through a Python API. The difference in approach is where the engine lives: chromadb's default deployment is the embedded library itself, while qdrant-client is explicitly a front end to a separate server process, with local mode described as a development and testing convenience. If your mental model is "import a library, get a database," chromadb matches it more directly. If your model is "develop against a local stand-in, deploy against a service," qdrant-client matches it.
Another comparison point is faiss, which is a similarity search library rather than a service. faiss gives you index structures in-process and no network layer, no payload filtering API and no scroll pagination. qdrant-client's scroll and payload filtering are part of the Qdrant API it wraps. The cost of that is the server you have to run.
Maintenance, releases and licence cost
The repository is not archived, and the last push was on 2026-09-15. Recent releases listed are v1.19.0 on 2026-08-04, v1.18.0 on 2026-05-11 and v1.17.1 on 2026-03-13, which is a cadence of roughly one minor release per quarter with patch releases between. For a client library that tracks a server API, that cadence is the thing to plan around: pinning qdrant-client in your lockfile is not optional if you want reproducible behaviour across a deploy.
The licence is Apache-2.0, declared both in the repository metadata and in pyproject.toml. That permits commercial use and modification with the usual notice and attribution conditions; it is not a copyleft licence, so it does not extend to your application code. This is a description of the licence text, not legal advice, and the LICENSE file in the repository root is the authoritative copy.
Upgrade cost is mostly the API surface. Because the package version tracks the Qdrant API, a minor bump can add methods rather than change them, but the pydantic and numpy constraints in pyproject.toml are the parts most likely to conflict with an existing environment. The optional fastembed and fastembed-gpu extras are the other upgrade hazard, since the README states they cannot coexist.
Editorial conclusion
Adopt qdrant-client if you already run Qdrant or want to prototype vector search in a notebook without a server, since local mode and server mode share one API. Skip it if your stack is not Python or if you want the engine's behaviour to be independent of client version, because the client carries its own release cadence and the Qdrant API surface is versioned alongside it. Before committing, check the pinned version in pyproject.toml against the server you target, and confirm whether you need the fastembed extra or will supply vectors yourself.
Frequently asked questions
What is qdrant-client used for?
It is the Python client library and SDK for the Qdrant vector search engine, providing type definitions for the Qdrant API and allowing both sync and async requests. It also adds helper methods for frequent operations such as initial collection uploading.
Can qdrant-client be run locally?
Yes. The README shows initializing the client with QdrantClient(":memory:") for an in-memory store or QdrantClient(path="path/to/db") to persist to disk, and states local mode is useful for development, prototyping and testing.
how to install qdrant client
The README gives a single command, pip install qdrant-client. To add local embedding support through FastEmbed, the documented extra is pip install qdrant-client[fastembed].
what is qdrant client
It is the client library and SDK for the Qdrant vector search engine. According to the README it contains type definitions for all Qdrant API methods and supports both REST and gRPC.
Is Qdrant DB free?
The qdrant-client repository is licensed under Apache-2.0, as declared in its metadata and pyproject.toml. The README separately notes that Qdrant Cloud offers a free tier account with 1GB RAM, and that remote inference is currently available only on paid plans.
Community notes