{"record":{"id":"f9802fa6e8db2833","repo":"chroma-core/chroma","slug":"the-httpx-python-package-is-not-installed-please-f9802f","errorCode":null,"errorMessage":"The httpx python package is not installed. Please install it with `pip install httpx`","messagePattern":"The httpx python package is not installed\\. Please install it with `pip install httpx`","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/chroma_cloud_splade_embedding_function.py","lineNumber":37,"sourceCode":"\nclass ChromaCloudSpladeEmbeddingFunction(SparseEmbeddingFunction[Documents]):\n    def __init__(\n        self,\n        api_key_env_var: str = \"CHROMA_API_KEY\",\n        model: ChromaCloudSpladeEmbeddingModel = ChromaCloudSpladeEmbeddingModel.SPLADE_PP_EN_V1,\n        include_tokens: bool = False,\n    ):\n        \"\"\"\n        Initialize the ChromaCloudSpladeEmbeddingFunction.\n\n        Args:\n            api_key_env_var (str, optional): Environment variable name that contains your API key.\n                Defaults to \"CHROMA_API_KEY\".\n        \"\"\"\n        try:\n            import httpx\n        except ImportError:\n            raise ValueError(\n                \"The httpx python package is not installed. Please install it with `pip install httpx`\"\n            )\n        self.api_key_env_var = api_key_env_var\n        # First, try to get API key from environment variable\n        self.api_key = os.getenv(self.api_key_env_var)\n        # If not found in env var, try to get it from existing client instances\n        if not self.api_key:\n            SharedSystemClient = _get_shared_system_client()\n            self.api_key = SharedSystemClient.get_chroma_cloud_api_key_from_clients()\n        # Raise error if still no API key found\n        if not self.api_key:\n            raise ValueError(\n                f\"API key not found in environment variable {self.api_key_env_var} \"\n                f\"or in any existing client instances\"\n            )\n        self.model = model\n        self.include_tokens = bool(include_tokens)\n        self._api_url = f\"{get_chroma_embed_url()}/embed_sparse\"","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/chroma_cloud_splade_embedding_function.py#L19-L55","documentation":"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.","triggerScenarios":"Constructing ChromaCloudSpladeEmbeddingFunction(...) (directly or via build_from_config) in an interpreter where `import httpx` fails.","commonSituations":"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.","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."],"exampleFix":"# before\nef = ChromaCloudSpladeEmbeddingFunction()  # ValueError: httpx not installed\n\n# after (pip install httpx)\nef = ChromaCloudSpladeEmbeddingFunction(\n    api_key_env_var=\"CHROMA_API_KEY\",\n    model=ChromaCloudSpladeEmbeddingModel.SPLADE_PP_EN_V1,\n)","handlingStrategy":"validation","validationCode":"import importlib.util\n\nif importlib.util.find_spec(\"httpx\") is None:\n    raise SystemExit(\"httpx is required for ChromaCloudSpladeEmbeddingFunction: pip install httpx\")\nef = ChromaCloudSpladeEmbeddingFunction()","typeGuard":null,"tryCatchPattern":"try:\n    ef = ChromaCloudSpladeEmbeddingFunction()\nexcept ValueError as e:\n    if \"httpx\" in str(e):\n        subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"httpx\"], check=True)\n        ef = ChromaCloudSpladeEmbeddingFunction()\n    else:\n        raise","preventionTips":["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."],"tags":["httpx","missing-dependency","chroma-cloud","splade","sparse-embeddings"],"backgroundTag":"missing-python-package","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}