cocoindex-io/cocoindex · error · ImportError

google-auth and google-api-python-client are required to use

Error message

google-auth and google-api-python-client are required to use the Google Drive source. Please install cocoindex[google_drive].

What it means

The Google Drive source connector requires the optional google-auth and google-api-python-client packages. At import time the module tries to import them (httplib2, google.oauth2, googleapiclient); on ImportError it raises an instructive ImportError telling the user to install the cocoindex[google_drive] extra.

Source

Thrown at python/cocoindex/connectors/google_drive/_source.py:23

"""

from __future__ import annotations

import asyncio
import io
from dataclasses import dataclass
from datetime import datetime
from pathlib import PurePath
from typing import Any, AsyncIterator, Iterator, Sequence, Self

try:
    import httplib2  # type: ignore
    from google.oauth2.service_account import Credentials  # type: ignore
    from google_auth_httplib2 import AuthorizedHttp  # type: ignore
    from googleapiclient.discovery import build  # type: ignore
    from googleapiclient.http import HttpRequest, MediaIoBaseDownload  # type: ignore
except ImportError as e:
    raise ImportError(
        "google-auth and google-api-python-client are required to use the Google Drive source. "
        "Please install cocoindex[google_drive]."
    ) from e

from cocoindex.resources import file


class DriveFilePath(file.FilePath[str]):
    """
    File path for Google Drive files.

    The resolved path is the Google Drive file ID (string).
    """

    __slots__ = ("_file_id",)

    _file_id: str

View on GitHub (pinned to e84aa99b32)

Solutions

Install the extra: pip install 'cocoindex[google_drive]' (or uv add 'cocoindex[google_drive]')
Install the packages directly: pip install google-auth google-auth-httplib2 google-api-python-client
Add cocoindex[google_drive] to your project's dependency list / requirements.txt

Example fix

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

Defensive patterns

Strategy: fallback

Validate before calling

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

Try / catch

try:
    from cocoindex.connectors import google_drive
except ImportError:
    google_drive = None  # surface a friendly setup message

Prevention

Always install optional extras: cocoindex[google_drive]
Pin extras in requirements.txt/pyproject dependencies
Run a dependency smoke-test in CI that imports every connector used

When it happens

Trigger: Importing cocoindex.connectors.google_drive (or using its source) in an environment where cocoindex was installed without the google_drive extra, e.g. plain `pip install cocoindex`.

Common situations: Fresh deployment/CI environments missing optional extras; switching machines without reinstalling extras; Docker images built from base requirements only.

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