cocoindex-io/cocoindex · error · ImportError

neo4j is required to use the Neo4j connector. Please install

Error message

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

What it means

This ImportError is raised at module import time when the neo4j Python driver package is not installed but the Neo4j connector module is imported. The neo4j driver is an optional dependency of cocoindex, enabled via the cocoindex[neo4j] extra. The import is wrapped so the failure surfaces with an actionable message instead of a bare ModuleNotFoundError.

Source

Thrown at python/cocoindex/connectors/neo4j/_target.py:42

import uuid as uuid_mod
from dataclasses import dataclass
from typing import (
    TYPE_CHECKING,
    Any,
    Callable,
    Collection,
    Generic,
    Literal,
    NamedTuple,
    Sequence,
)

from typing_extensions import TypeVar

try:
    import neo4j as _neo4j  # type: ignore[import-not-found]
except ImportError as e:
    raise ImportError(
        "neo4j is required to use the Neo4j connector. Please install cocoindex[neo4j]."
    ) from e

if TYPE_CHECKING:
    AsyncDriver = Any
else:
    AsyncDriver = _neo4j.AsyncDriver

import msgspec
import numpy as np

import cocoindex as coco
from cocoindex._internal.context_keys import ContextKey, ContextProvider
from cocoindex._internal.datatype import (
    AnyType,
    MappingType,
    RecordType,
    SequenceType,

View on GitHub (pinned to e84aa99b32)

Solutions

Install with the extra: pip install 'cocoindex[neo4j]' (or uv add 'cocoindex[neo4j]').
Verify installation: python -c "import neo4j".
If neo4j support is unneeded, avoid importing the neo4j connector module/entry point.

Example fix

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

Defensive patterns

Strategy: fallback

Validate before calling

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

Try / catch

try:
    from cocoindex.connectors import neo4j
except ImportError as e:
    raise SystemExit("Neo4j support missing. Run: pip install 'cocoindex[neo4j]'") from e

Prevention

Always install optional connectors via extras in pyproject/requirements
Pin cocoindex[neo4j] in CI and Docker images
Smoke-test imports of all used connectors at app startup

When it happens

Trigger: Importing python/cocoindex/connectors/neo4j/_target.py (or the neo4j connector package) in an environment where the neo4j package was never installed — e.g. cocoindex installed as `pip install cocoindex` without extras, or in a fresh venv missing the extra.

Common situations: Deploying to production without the optional extra; switching virtualenvs and forgetting dev dependency groups; a Dockerfile that installs base requirements only; CI running tests that import the connector.

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