Install & Compatibility
Where this runs
tested against v1.1.0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 6.362s · 168.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 11.6s · import 5.008s · 171MB
173MB installed
● package 173MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
QdrantVectorStore
✓ from langchain_qdrant import QdrantVectorStore
This is the recommended and modern class for Qdrant integration.
Qdrant
✓ from langchain_qdrant import Qdrant
✗ from langchain.vectorstores import Qdrant
The `Qdrant` class within `langchain_qdrant` is now deprecated in favor of `QdrantVectorStore`. Older import paths from `langchain.vectorstores` are part of the legacy `langchain` package and should be avoided for new projects.
QdrantClient
✓ from qdrant_client import QdrantClient
Required to initialize the underlying Qdrant client, which is then passed to `QdrantVectorStore`.
This quickstart demonstrates how to set up an in-memory Qdrant client, initialize a `QdrantVectorStore` with `OpenAIEmbeddings`, add documents, and perform a similarity search. Ensure you have `langchain-openai` installed for the embeddings. For persistent storage or remote Qdrant instances, adjust the `QdrantClient` initialization.
import os
from qdrant_client import QdrantClient
from qdrant_client.http.models import Distance, VectorParams
from langchain_qdrant import QdrantVectorStore
from langchain_openai import OpenAIEmbeddings # Requires `pip install langchain-openai`
from langchain_core.documents import Document
# Set your OpenAI API key for embeddings (replace with your preferred embedding model)
os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "sk-...")
# 1. Initialize an in-memory Qdrant client
client = QdrantClient(":memory:")
# 2. Define collection parameters (e.g., for OpenAI embeddings)
collection_name = "my_langchain_collection"
embedding_dimension = 1536 # For text-embedding-ada-002 or text-embedding-3-small
client.create_collection(
collection_name=collection_name,
vectors_config=VectorParams(size=embedding_dimension, distance=Distance.COSINE),
)
# 3. Initialize the embedding model
embeddings = OpenAIEmbeddings()
# 4. Create a QdrantVectorStore instance
vector_store = QdrantVectorStore(
client=client,
collection_name=collection_name,
embedding=embeddings,
)
# 5. Add documents to the vector store
documents = [
Document(page_content="The quick brown fox jumps over the lazy dog.", metadata={"source": "sentence 1"}),
Document(page_content="LangChain provides many integrations with vector stores.", metadata={"source": "sentence 2"}),
Document(page_content="Qdrant is an open-source vector database.", metadata={"source": "sentence 3"}),
]
vector_store.add_documents(documents)
# 6. Perform a similarity search
query = "What is Qdrant?"
found_docs = vector_store.similarity_search(query, k=1)
print(f"Query: {query}")
for doc in found_docs:
print(f"- Content: {doc.page_content}, Metadata: {doc.metadata}")
Debug
Known issues
deprecatedThe `Qdrant` class is deprecated in favor of `QdrantVectorStore`. While still supported, new development should use `QdrantVectorStore` for modern functionalities and better API design.fixMigrate code to use `from langchain_qdrant import QdrantVectorStore`. Review LangChain's official documentation for migration guides related to vector store integrations.
affects: All versions since the introduction of `QdrantVectorStore` (around v0.1.x of `langchain-qdrant`).
gotchaWhen using `QdrantVectorStore` with Qdrant's new Query API (for features like sparse or hybrid retrieval), Qdrant server version 1.10.0 or above is required. Older Qdrant server versions may not support all features, leading to unexpected behavior or errors.fixEnsure your Qdrant server instance is running version 1.10.0 or newer if you plan to use advanced retrieval modes (e.g., hybrid search).
affects: All `langchain-qdrant` versions leveraging new Qdrant Query API features.
gotchaPerformance bottlenecks can occur when dealing with large document collections, primarily during the embedding process and initial data loading into Qdrant. Default settings for Qdrant collections might not be optimized for bulk inserts.fixTo improve performance, consider batching documents during the embedding process (e.g., batches of 50-100). For Qdrant, tweak HNSW parameters (e.g., `m=16`, `ef_construct=200`) during collection creation for faster writes. Utilize Qdrant's async client for bulk operations, and optimize Docker memory settings if running locally.
affects: All versions.
gotchaUpdating existing documents in a Qdrant collection via `add_documents` or `add_texts` requires passing the same `id` as the original document. Otherwise, new points will be created instead of overwriting existing ones, leading to duplicate entries or unexpected search results.fixWhen updating, ensure you explicitly provide the original `id` for the documents you wish to modify. For example: `vector_store.add_documents([my_updated_doc], ids=[original_id])`.
affects: All versions.
breakingWhile `langchain-qdrant` itself adheres to semantic versioning, the broader LangChain ecosystem (especially the `langchain` and `langchain-community` packages) has undergone significant API changes, notably with the transition to LangChain Expression Language (LCEL) and a more modular structure around LangChain v1.0. This can lead to incompatibility if other LangChain components are not aligned.fixAlways check the compatibility of `langchain-qdrant` with your specific `langchain-core` and other `langchain` ecosystem package versions. Refer to the main LangChain migration guides for updates on core framework changes, especially if migrating from pre-1.0 versions.
affects: Potentially all `langchain-qdrant` versions when used with older or unaligned `langchain` ecosystem packages.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'qdrant_client'
The `langchain-qdrant` library depends on the `qdrant-client` Python package, which is not installed in your environment.
fixInstall the `qdrant-client` package using pip: `pip install qdrant-client`.
_InactiveRpcError: Connection refused to 127.0.0.1:6334
This error typically occurs when `prefer_grpc=True` is used to connect to Qdrant, but the Qdrant server (especially in Docker environments) does not have gRPC enabled or its gRPC port (6334) is not exposed.
fixEnsure your Qdrant server has gRPC enabled and port 6334 exposed in its configuration. Alternatively, set `prefer_grpc=False` in your `Qdrant` or `QdrantVectorStore` initialization to use the HTTP REST API on port 6333.
qdrant_client.http.exceptions.UnexpectedResponse: Unexpected Response: 404 (Not Found)
This error indicates that the `langchain-qdrant` client is trying to use an API endpoint or feature (like the new Query API) that is not supported by the version of the Qdrant server you are running. Many advanced features require Qdrant server v1.10.0 or newer.
fixUpgrade your Qdrant server to version 1.10.0 or higher to support the features being used by `langchain-qdrant`.
ValueError: Only one of 'path', 'url', 'host' or 'client' can be specified
This error happens when you provide multiple, conflicting connection parameters (e.g., both `path` for local storage and `url` for a remote server) when initializing a `Qdrant` or `QdrantVectorStore` instance. These methods require a single, unambiguous way to connect to Qdrant.
fixChoose only one method for connecting to Qdrant and provide the corresponding parameters. For example, use `path='./qdrant_data'` for local persistent storage, or `url='http://localhost:6333'` for a remote server, but not both.
Upgrade
Version history
1.1.0latest on PyPI · released Oct 22, 2025
Audit
Dependencies
langchain-corerequiredCore LangChain functionalities.
pydanticrequiredData validation and settings management.
qdrant-clientrequiredOfficial Python client for interacting with Qdrant.
fastembedoptionalOptional dependency for FastEmbed-based sparse embeddings.