cocoindex-io/cocoindex · error · ImportError

qdrant-client is required to use the Qdrant connector. Pleas

Error message

qdrant-client is required to use the Qdrant connector. Please install cocoindex[qdrant].

What it means

Import-time guard for the Qdrant connector: `qdrant_client` is not installed in the environment, so importing the connector module raises immediately. The connector is an optional dependency, isolated behind the `cocoindex[qdrant]` extra.

Source

Thrown at python/cocoindex/connectors/qdrant/_target.py:31

import msgspec
from dataclasses import dataclass
from typing import (
    Any,
    Collection,
    Generic,
    Literal,
    NamedTuple,
    Sequence,
    cast,
)


try:
    from qdrant_client import QdrantClient
    from qdrant_client.http import models as qdrant_models
except ImportError as e:
    raise ImportError(
        "qdrant-client is required to use the Qdrant connector. Please install cocoindex[qdrant]."
    ) from e

import cocoindex as coco
from cocoindex.connectorkits import statediff, target
from cocoindex.connectorkits.fingerprint import fingerprint_object
from cocoindex._internal.datatype import TypeChecker
from cocoindex.resources import schema as res_schema
from cocoindex._internal.context_keys import ContextKey, ContextProvider

# Public alias for Qdrant point model
PointStruct = qdrant_models.PointStruct

# Type aliases
_PointId = str | int
_PointFingerprint = bytes
_POINT_ID_CHECKER: TypeChecker[str | int] = TypeChecker(str | int)  # type: ignore[arg-type]

View on GitHub (pinned to e84aa99b32)

Solutions

Install the extra: `pip install 'cocoindex[qdrant]'` (or `uv add 'cocoindex[qdrant]'`).
Or install the client directly: `pip install qdrant-client` with a compatible version.
Regenerate/rebuild your environment/lockfile to include the optional dependency.

Example fix

// before
pip install cocoindex
// after
pip install "cocoindex[qdrant]"

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("qdrant_client") is None:
    raise RuntimeError("Install with: pip install 'cocoindex[qdrant]'")

Try / catch

try:
    from cocoindex.connectors import qdrant
except ImportError as e:
    if "qdrant-client is required" in str(e):
        sys.exit("Run: pip install 'cocoindex[qdrant]'")
    raise

Prevention

Always install optional extras you use: cocoindex[qdrant].
Pin extras in requirements/pyproject so CI and Docker include them.
Add a smoke import of all connectors in CI.

When it happens

Trigger: Running `import cocoindex.connectors.qdrant` (or importing the module that pulls it in) in an environment where only the base cocoindex package was installed.

Common situations: Fresh environment/CI where optional extras weren't installed; adding Qdrant as a target after initially installing cocoindex without extras; Docker images that omit optional deps.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/e066d4edcd5eefbe. Report an issue: GitHub.