cocoindex-io/cocoindex · error · ImportError

turbopuffer is required to use the Turbopuffer connector. Pl

Error message

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

What it means

The turbopuffer connector depends on the optional third-party `turbopuffer` Python package. Importing the connector module executes a try/except around `from turbopuffer import ...`, and when the package is missing it re-raises an ImportError telling you to install the `cocoindex[turbopuffer]` extra.

Source

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

from __future__ import annotations

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

import msgspec
import numpy as np

try:
    from turbopuffer import AsyncTurbopuffer, NotFoundError  # type: ignore
except ImportError as e:
    raise ImportError(
        "turbopuffer is required to use the Turbopuffer connector. "
        "Please install cocoindex[turbopuffer]."
    ) 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


# Type aliases
_RowId = str | int
_RowFingerprint = bytes
_ROW_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[turbopuffer]"` (or `uv add "cocoindex[turbopuffer]"`).
Or install the package directly: `pip install turbopuffer`.
Update requirements/pyproject so the extra is included in the environment that runs the pipeline.
Verify with `python -c "import turbopuffer"` before re-running.

Example fix

// before (shell)
pip install cocoindex
// after (shell)
pip install "cocoindex[turbopuffer]"

Defensive patterns

Strategy: fallback

Validate before calling

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

Type guard

def turbopuffer_available() -> bool:
    import importlib.util
    return importlib.util.find_spec("turbopuffer") is not None

Try / catch

try:
    from cocoindex.connectors import turbopuffer
except ImportError as e:
    if "cocoindex[turbopuffer]" in str(e):
        raise SystemExit("Run: pip install 'cocoindex[turbopuffer]'") from e
    raise

Prevention

Install optional extras in CI and dev: cocoindex[turbopuffer].
Pin the extra in pyproject/requirements for every environment that imports the connector.
Guard imports at module top so failures surface at startup, not mid-pipeline.
Run `python -c "import turbopuffer"` in a smoke test.

When it happens

Trigger: Any import of `cocoindex.connectors.turbopuffer` (e.g. `from cocoindex.connectors import turbopuffer`) in an environment where the `turbopuffer` distribution is not installed.

Common situations: Installing plain `cocoindex` instead of `cocoindex[turbopuffer]`; a fresh CI/dev environment without the extra; adding the import in code after switching machines; pinned requirements missing the optional dependency.

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