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

The constructor of ChromaCloudQwenEmbeddingFunction (the Qwen dense embedding client for Chroma Cloud) does `import httpx` and raises ValueError on ImportError. httpx is the HTTP client this function uses for all requests to the Chroma Embed API, and it is an optional dependency not bundled with the base chromadb install.

Source

Thrown at chromadb/utils/embedding_functions/chroma_cloud_qwen_embedding_function.py:55

        instructions: ChromaCloudQwenEmbeddingInstructions = CHROMA_CLOUD_QWEN_DEFAULT_INSTRUCTIONS,
        api_key_env_var: str = "CHROMA_API_KEY",
    ):
        """
        Initialize the ChromaCloudQwenEmbeddingFunction.

        Args:
            model (ChromaCloudQwenEmbeddingModel): The specific Qwen model to use for embeddings.
            task (str, optional): The task for which embeddings are being generated. If None or empty,
                empty instructions will be used for both documents and queries.
            instructions (ChromaCloudQwenEmbeddingInstructions, optional): A dictionary containing
                custom instructions to use for the specified Qwen model. Defaults to CHROMA_CLOUD_QWEN_DEFAULT_INSTRUCTIONS.
            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(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 {api_key_env_var} "
                f"or in any existing client instances"
            )

        self.model = model

View on GitHub (pinned to aecdd12c8a)

Solutions

1. pip install httpx in the same environment running your app.
2. Add httpx to requirements.txt / pyproject.toml dependencies for any deployment using Chroma Cloud embedding functions.
3. If it should already be installed, verify with `python -c "import httpx"` in the exact interpreter/venv, and check for a conflicting local httpx.py file shadowing the package.

Example fix

# before
from chromadb.utils.embedding_functions import ChromaCloudQwenEmbeddingFunction
ef = ChromaCloudQwenEmbeddingFunction(...)  # ValueError: httpx not installed

# after (pip install httpx)
ef = ChromaCloudQwenEmbeddingFunction(model=ChromaCloudQwenEmbeddingModel.QWEN3_EMBEDDING_0p6B, task="nl_to_code")

import importlib.util

if importlib.util.find_spec("httpx") is None:
    raise SystemExit("httpx is required for ChromaCloudQwenEmbeddingFunction: pip install httpx")
ef = ChromaCloudQwenEmbeddingFunction(model=ChromaCloudQwenEmbeddingModel.QWEN3_EMBEDDING_0p6B, task=None)

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

When it happens

Trigger: Instantiating ChromaCloudQwenEmbeddingFunction(model=ChromaCloudQwenEmbeddingModel.QWEN3_EMBEDDING_0p6B, task=...) in an environment where httpx is not installed (module resolution fails at the `import httpx` inside __init__).

Common situations: Fresh virtualenv with chromadb but without optional extras; Docker/CI slim images that strip optional deps; a different interpreter than the one where httpx was pip-installed.

Related errors

• The httpx python package is not installed. Please install it
• API key not found in environment variable {api_key_env_var}
• Unknown error
• The model cannot be changed after the embedding function has
• The task cannot be changed after the embedding function has

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