cocoindex-io/cocoindex · error · ImportError

zvec is required to use the zvec connector. Please install…

Error message

zvec is required to use the zvec connector. Please install cocoindex[zvec].

What it means

The zvec connector requires the optional 'zvec' package. Importing the connector module (python/cocoindex/connectors/zvec/_target.py) raises ImportError with an install hint if the underlying zvec library is not installed, because the connector cannot function without it.

Solutions

pip install "cocoindex[zvec]" (or uv add "cocoindex[zvec]")
Verify `import zvec` works in the same interpreter
Check the environment/venv used at runtime matches where cocoindex is installed

Example fix

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

Defensive patterns

Strategy: fallback

Validate before calling

import importlib.util
if importlib.util.find_spec("zvec") is None:
    raise SystemExit('Install: pip install "cocoindex[zvec]"')

Try / catch

try:
    from cocoindex.connectors import zvec
except ImportError as e:
    if "cocoindex[zvec]" in str(e):
        sys.exit('Missing dependency: pip install "cocoindex[zvec]"')
    raise

Prevention

Add cocoindex[zvec] to project dependencies, not bare cocoindex
Pin the extra in CI requirements
Verify optional extras in a smoke test at env setup

When it happens

Trigger: Importing or using anything from cocoindex.connectors.zvec without the zvec package installed; using the cocoindex[zvec] extra-less base install.

Common situations: Fresh environment missing optional dependency; CI image installs cocoindex base but not extras; dependency removed by a lockfile pin conflict.

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/ff0accda41fd9adb. Report an issue: GitHub.

Appendix: source

Thrown at python/cocoindex/connectors/zvec/_target.py:46

from typing import (
    Any,
    Callable,
    Collection,
    Generic,
    Iterator,
    Literal,
    NamedTuple,
    Sequence,
    cast,
)

import numpy as np
from typing_extensions import TypeVar

try:
    import zvec as _zvec
except ImportError as e:
    raise ImportError(
        "zvec is required to use the zvec connector. Please install cocoindex[zvec]."
    ) from e

import msgspec

import cocoindex as coco
from cocoindex.connectorkits import statediff, target
from cocoindex.connectorkits.fingerprint import fingerprint_object
from cocoindex._internal.context_keys import ContextKey, ContextProvider
from cocoindex._internal.datatype import (
    RecordType,
    SequenceType,
    TypeChecker,
    analyze_type_info,
    is_record_type,
)
from cocoindex.resources import schema as res_schema

View on GitHub (pinned to e84aa99b32)