chroma-core/chroma · error · ValueError

The perplexityai python package is not installed. Please ins

Error message

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

What it means

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.

Source

Thrown at chromadb/utils/embedding_functions/perplexity_embedding_function.py:41

        api_key_env_var: str = "PERPLEXITY_API_KEY",
        dimensions: Optional[int] = None,
    ):
        """
        Initialize the PerplexityEmbeddingFunction.

        Args:
            api_key_env_var (str, optional): Environment variable name that contains your API key for the Perplexity API.
                Defaults to "PERPLEXITY_API_KEY".
            model_name (str, optional): The name of the model to use for text embeddings.
                Defaults to "pplx-embed-v1-0.6b".
            api_key (str, optional): API key for the Perplexity API. If not provided, will look for it in the environment variable.
            dimensions (int, optional): Perplexity embeddings support Matryoshka representation learning, allowing you
                to reduce embedding dimensions while maintaining quality.
        """
        try:
            import perplexity
        except ImportError:
            raise ValueError(
                "The perplexityai python package is not installed. Please install it with `pip install perplexityai`"
            )

        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("PERPLEXITY_API_KEY") is not None:
            self.api_key_env_var = "PERPLEXITY_API_KEY"
        else:
            self.api_key_env_var = api_key_env_var

        self.api_key = api_key or os.getenv(self.api_key_env_var)
        if not self.api_key:
            raise ValueError(

View on GitHub (pinned to aecdd12c8a)

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.

Example fix

// before
from chromadb.utils.embedding_functions import PerplexityEmbeddingFunction
ef = PerplexityEmbeddingFunction()  # ValueError: The perplexityai python package is not installed...

# after
# shell: pip install perplexityai
import importlib.util
if importlib.util.find_spec("perplexity") is None:
    raise RuntimeError("Run: pip install perplexityai")
ef = PerplexityEmbeddingFunction()

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec("perplexity") is None:
    raise RuntimeError("Optional dependency missing — run: pip install perplexityai")

ef = PerplexityEmbeddingFunction()

Type guard

import importlib.util

def perplexity_available() -> bool:
    return importlib.util.find_spec("perplexity") is not None

Try / catch

try:
    ef = PerplexityEmbeddingFunction()
except ValueError as e:
    if "perplexityai" in str(e):
        raise RuntimeError("Install it with: pip install perplexityai") from e
    raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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