{"record":{"id":"22934acaf551658a","repo":"chroma-core/chroma","slug":"the-perplexityai-python-package-is-not-installed","errorCode":null,"errorMessage":"The perplexityai python package is not installed. Please install it with `pip install perplexityai`","messagePattern":"The perplexityai python package is not installed\\. Please install it with `pip install perplexityai`","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/perplexity_embedding_function.py","lineNumber":41,"sourceCode":"        api_key_env_var: str = \"PERPLEXITY_API_KEY\",\n        dimensions: Optional[int] = None,\n    ):\n        \"\"\"\n        Initialize the PerplexityEmbeddingFunction.\n\n        Args:\n            api_key_env_var (str, optional): Environment variable name that contains your API key for the Perplexity API.\n                Defaults to \"PERPLEXITY_API_KEY\".\n            model_name (str, optional): The name of the model to use for text embeddings.\n                Defaults to \"pplx-embed-v1-0.6b\".\n            api_key (str, optional): API key for the Perplexity API. If not provided, will look for it in the environment variable.\n            dimensions (int, optional): Perplexity embeddings support Matryoshka representation learning, allowing you\n                to reduce embedding dimensions while maintaining quality.\n        \"\"\"\n        try:\n            import perplexity\n        except ImportError:\n            raise ValueError(\n                \"The perplexityai python package is not installed. Please install it with `pip install perplexityai`\"\n            )\n\n        if api_key is not None:\n            warnings.warn(\n                \"Direct api_key configuration will not be persisted. \"\n                \"Please use environment variables via api_key_env_var for persistent storage.\",\n                DeprecationWarning,\n            )\n\n        if os.getenv(\"PERPLEXITY_API_KEY\") is not None:\n            self.api_key_env_var = \"PERPLEXITY_API_KEY\"\n        else:\n            self.api_key_env_var = api_key_env_var\n\n        self.api_key = api_key or os.getenv(self.api_key_env_var)\n        if not self.api_key:\n            raise ValueError(","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/perplexity_embedding_function.py#L23-L59","documentation":"PerplexityEmbeddingFunction.__init__ unconditionally does `import perplexity` and converts ImportError into this ValueError, telling you the optional dependency is absent. Chroma does not ship the perplexityai package, so the embedding function is unusable until you install it. The error occurs at construction time, not at the first embed call.","triggerScenarios":"Instantiating PerplexityEmbeddingFunction(...) in an environment where `pip install perplexityai` was never run — including fresh virtualenvs, slim Docker images, and CI runners where only chromadb itself was installed.","commonSituations":"requirements.txt lists chromadb but not perplexityai; installing in a different virtualenv/conda env than the one running the code; a Docker build that copies code but prunes 'unused' optional deps; CI green locally (package present globally) but failing in a clean build.","solutions":["Install the package into the exact environment that runs your code: pip install perplexityai (add it to requirements.txt / pyproject dependencies).","Verify the interpreter matches: `python -m pip install perplexityai` using the same `python` that imports chromadb.","In Docker, add `RUN pip install perplexityai` to the image build stage.","If the install itself fails, check the package name spelling — it is perplexityai, not perplexity — and your Python version compatibility."],"exampleFix":"// before\nfrom chromadb.utils.embedding_functions import PerplexityEmbeddingFunction\nef = PerplexityEmbeddingFunction()  # ValueError: The perplexityai python package is not installed...\n\n# after\n# shell: pip install perplexityai\nimport importlib.util\nif importlib.util.find_spec(\"perplexity\") is None:\n    raise RuntimeError(\"Run: pip install perplexityai\")\nef = PerplexityEmbeddingFunction()","handlingStrategy":"validation","validationCode":"import importlib.util\n\nif importlib.util.find_spec(\"perplexity\") is None:\n    raise RuntimeError(\"Optional dependency missing — run: pip install perplexityai\")\n\nef = PerplexityEmbeddingFunction()","typeGuard":"import importlib.util\n\ndef perplexity_available() -> bool:\n    return importlib.util.find_spec(\"perplexity\") is not None","tryCatchPattern":"try:\n    ef = PerplexityEmbeddingFunction()\nexcept ValueError as e:\n    if \"perplexityai\" in str(e):\n        raise RuntimeError(\"Install it with: pip install perplexityai\") from e\n    raise","preventionTips":["Declare every optional embedding dependency your app uses in requirements.txt/pyproject, not ad-hoc installs.","Use one virtualenv per project and install with `python -m pip` to avoid interpreter drift.","Add `python -c \"import perplexity\"` to container builds so missing deps fail the build, not runtime."],"tags":["perplexity","embedding","dependency","import","pip","chroma"],"backgroundTag":"missing-python-dependency","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}