chroma-core/chroma · error · ValueError

The httpx python package is not installed. Please install it

Error message

The httpx python package is not installed. Please install it with `pip install httpx`

What it means

JinaEmbeddingFunction talks to https://api.jina.ai/v1/embeddings over HTTP using the httpx client, which it imports lazily in __init__. chromadb does not depend on httpx unconditionally, so if httpx is not installed the ImportError becomes this ValueError at construction. Note the constructor imports both httpx and PIL.Image — either missing aborts initialization.

Source

Thrown at chromadb/utils/embedding_functions/jina_embedding_function.py:67

                Defaults to "jina-embeddings-v2-base-en".
            task (str, optional): The task to use for the Jina AI API.
                Defaults to None.
            late_chunking (bool, optional): Whether to use late chunking for the Jina AI API.
                Defaults to None.
            truncate (bool, optional): Whether to truncate the Jina AI API.
                Defaults to None.
            dimensions (int, optional): The number of dimensions to use for the Jina AI API.
                Defaults to None.
            embedding_type (str, optional): The type of embedding to use for the Jina AI API.
                Defaults to None.
            normalized (bool, optional): Whether to normalize the Jina AI API.
                Defaults to None.

        """
        try:
            import httpx
        except ImportError:
            raise ValueError(
                "The httpx python package is not installed. Please install it with `pip install httpx`"
            )
        try:
            self._PILImage = importlib.import_module("PIL.Image")
        except ImportError:
            raise ValueError(
                "The PIL python package is not installed. Please install it with `pip install pillow`"
            )

        if api_key is not None:
            warnings.warn(
                "Direct api_key configuration will not be persisted. "
                "Please use environment variables via api_key_env_var for persistent storage.",
                DeprecationWarning,
            )

        if os.getenv("JINA_API_KEY") is not None:
            self.api_key_env_var = "JINA_API_KEY"

View on GitHub (pinned to aecdd12c8a)

Solutions

pip install httpx in the interpreter running chromadb
Verify: python -c "import httpx; print(httpx.__version__)"
Add httpx explicitly to requirements.txt so lock/prune tools do not drop it

Example fix

# before
from chromadb.utils.embedding_functions import JinaEmbeddingFunction
ef = JinaEmbeddingFunction(model_name="jina-clip-v1")  # ValueError: httpx missing

# after
# pip install httpx
import importlib.util
if importlib.util.find_spec("httpx") is None:
    raise SystemExit("pip install httpx")
ef = JinaEmbeddingFunction(model_name="jina-clip-v1")

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec("httpx") is None:
    raise SystemExit("Jina EF needs httpx: pip install httpx")

from chromadb.utils.embedding_functions import JinaEmbeddingFunction
ef = JinaEmbeddingFunction(model_name="jina-clip-v1")

Try / catch

try:
    ef = JinaEmbeddingFunction(model_name="jina-clip-v1")
except ValueError as e:
    if "httpx" in str(e):
        raise RuntimeError("pip install httpx") from e
    raise

Prevention

Declare httpx explicitly next to chromadb in requirements (don't rely on transitive presence)
Include a find_spec-based dependency preflight for every HTTP-based EF you enable
Re-run dependency checks after pip-sync/uv-sync pruning steps

When it happens

Trigger: JinaEmbeddingFunction(model_name='jina-clip-v1') in an environment without httpx (e.g. minimal chromadb install, pruned container image); dependency resolver removing httpx after a pip-sync; fresh venv created from a lockfile that omits it.

Common situations: Slim Docker images that only install chromadb; CI caching stale environments; local dev installing chromadb with minimal extras then switching from a requests-based EF to the Jina EF.

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/b3db2206602ca2d7. Report an issue: GitHub.