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

ChromaCloudSpladeEmbeddingFunction.__init__ runs `import httpx` and raises ValueError on ImportError. This sparse (SPLADE) embedding function talks to the Chroma Cloud /embed_sparse endpoint through an httpx.Client, and httpx is an optional dependency that base chromadb does not install.

Source

Thrown at chromadb/utils/embedding_functions/chroma_cloud_splade_embedding_function.py:37

class ChromaCloudSpladeEmbeddingFunction(SparseEmbeddingFunction[Documents]):
    def __init__(
        self,
        api_key_env_var: str = "CHROMA_API_KEY",
        model: ChromaCloudSpladeEmbeddingModel = ChromaCloudSpladeEmbeddingModel.SPLADE_PP_EN_V1,
        include_tokens: bool = False,
    ):
        """
        Initialize the ChromaCloudSpladeEmbeddingFunction.

        Args:
            api_key_env_var (str, optional): Environment variable name that contains your API key.
                Defaults to "CHROMA_API_KEY".
        """
        try:
            import httpx
        except ImportError:
            raise ValueError(
                "The httpx python package is not installed. Please install it with `pip install httpx`"
            )
        self.api_key_env_var = api_key_env_var
        # First, try to get API key from environment variable
        self.api_key = os.getenv(self.api_key_env_var)
        # If not found in env var, try to get it from existing client instances
        if not self.api_key:
            SharedSystemClient = _get_shared_system_client()
            self.api_key = SharedSystemClient.get_chroma_cloud_api_key_from_clients()
        # Raise error if still no API key found
        if not self.api_key:
            raise ValueError(
                f"API key not found in environment variable {self.api_key_env_var} "
                f"or in any existing client instances"
            )
        self.model = model
        self.include_tokens = bool(include_tokens)
        self._api_url = f"{get_chroma_embed_url()}/embed_sparse"

View on GitHub (pinned to aecdd12c8a)

Solutions

pip install httpx in the environment that runs the code.
Pin httpx in your dependency file wherever SPLADE embeddings are used.
Diagnose shadowing with `python -c "import httpx; print(httpx.__file__)"` if pip claims it is installed.

Example fix

# before
ef = ChromaCloudSpladeEmbeddingFunction()  # ValueError: httpx not installed

# after (pip install httpx)
ef = ChromaCloudSpladeEmbeddingFunction(
    api_key_env_var="CHROMA_API_KEY",
    model=ChromaCloudSpladeEmbeddingModel.SPLADE_PP_EN_V1,
)

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec("httpx") is None:
    raise SystemExit("httpx is required for ChromaCloudSpladeEmbeddingFunction: pip install httpx")
ef = ChromaCloudSpladeEmbeddingFunction()

Try / catch

try:
    ef = ChromaCloudSpladeEmbeddingFunction()
except ValueError as e:
    if "httpx" in str(e):
        subprocess.run([sys.executable, "-m", "pip", "install", "httpx"], check=True)
        ef = ChromaCloudSpladeEmbeddingFunction()
    else:
        raise

Prevention

List httpx as an explicit dependency in services using SPLADE embeddings.
Validate optional imports at boot with importlib.util.find_spec.
Use one lock file for app + optional extras so CI matches production.

When it happens

Trigger: Constructing ChromaCloudSpladeEmbeddingFunction(...) (directly or via build_from_config) in an interpreter where `import httpx` fails.

Common situations: Slim production images; a venv created from a partial requirements list; CI cache restored without optional packages; a local file named httpx.py shadowing the real package.

Related errors

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