cocoindex-io/cocoindex · error · ImportError

asyncpg is required to use the PostgreSQL connector. Please

Error message

asyncpg is required to use the PostgreSQL connector. Please install cocoindex[postgres].

What it means

The PostgreSQL target connector depends on the asyncpg package, which is an optional dependency of cocoindex. Importing the connector without asyncpg installed raises ImportError with instructions to install the extra.

Source

Thrown at python/cocoindex/connectors/postgres/_target.py:36

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


from typing_extensions import TypeVar

try:
    import asyncpg  # type: ignore
except ImportError as e:
    raise ImportError(
        "asyncpg is required to use the PostgreSQL connector. "
        "Please install cocoindex[postgres]."
    ) from e

import numpy as np

import cocoindex as coco
from cocoindex.connectorkits import statediff, target
from cocoindex.connectorkits.fingerprint import fingerprint_object
from cocoindex._internal.datatype import (
    AnyType,
    MappingType,
    SequenceType,
    RecordType,
    TypeChecker,
    UnionType,
    analyze_type_info,
    is_record_type,

View on GitHub (pinned to e84aa99b32)

Solutions

Run `pip install 'cocoindex[postgres]'` (or `uv add 'cocoindex[postgres]'`).
Verify with `python -c "import asyncpg"` that the dependency resolves in the active environment.
If deploying, add the postgres extra to your dependency/lock file.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

try:
    import asyncpg
except ImportError:
    raise SystemExit("Install with: pip install 'cocoindex[postgres]'")

Try / catch

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

Prevention

Install extras explicitly: cocoindex[postgres] in pyproject/requirements.
Pin dependencies and use a lockfile so CI matches local envs.
Smoke-test imports at application startup, not deep in a request path.

When it happens

Trigger: Running `import cocoindex.connectors.postgres` (or code importing the _target module) in an environment where cocoindex was installed without the [postgres] extra.

Common situations: Fresh virtualenv or CI container with bare `pip install cocoindex`; deploying to a server where the extras group was omitted; switching Python environments.

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