Perplexity AI Python SDK

0.30.1 verified Tue May 12 auth: no python install: verified quickstart: verified

Official Python SDK for the Perplexity API — web-grounded chat completions with real-time search, citations, and reasoning.

pip install perplexityai

Common errors

error ModuleNotFoundError: No module named 'perplexity' ↓

cause The `perplexityai` Python package is not installed in your current environment.

fix

Install the package using pip: pip install perplexityai

error perplexity.AuthenticationError: Invalid API key. ↓

cause The API key provided is either missing, incorrect, or expired, leading to authentication failure.

fix

Ensure your PERPLEXITY_API_KEY environment variable is correctly set with a valid key, or pass it explicitly when initializing the Perplexity client: client = Perplexity(api_key="your_api_key_here")

error 400 'messages' is a required property. ↓

cause When making a chat completions request, the `messages` parameter is either not provided, is empty, or does not conform to the expected structure where each message object must have at least a 'role' and 'content' field.

fix

Provide a list of message dictionaries, each with a 'role' (e.g., 'user', 'assistant') and 'content' key. Example: messages=[{"role": "user", "content": "Hello!"}]

error Perplexity API error (400): {"error":{"message":"Invalid model 'perplexity/sonar-pro'. Permitted models can be found in the documentation at https://docs.perplexity.ai/getting-started/models.","type":"invalid_model","code":400}} ↓

cause An incorrect or improperly formatted model name was specified in the API request. Some environments or examples might prepend 'perplexity/' to the model name, which the API does not expect.

fix

Use the exact model name without any prefixes, such as 'sonar-small-online', 'sonar-medium-online', 'sonar-large-online', or 'llama-3-sonar-large-32k'. Refer to the official Perplexity documentation for the list of supported models.

error AttributeError: 'str' object has no attribute 'choices' ↓

cause This typically occurs when the API returns an error message as a string instead of a structured response object with a 'choices' attribute, or if you are trying to access 'choices' on a non-response object due to an unexpected API outcome (e.g., rate limiting, internal server error).

fix

Implement error handling (e.g., try-except blocks for perplexity.APIStatusError or perplexity.RateLimitError) to catch non-successful responses before attempting to access response attributes. Inspect the raw API response to understand its format in case of an error.

Warnings

breaking All llama-3.1-sonar-* and llama-3-sonar-* model names removed Feb 22, 2025. Using them returns a 404/model-not-found error. ↓

fix Use current Sonar family: sonar, sonar-pro, sonar-reasoning, sonar-reasoning-pro, sonar-deep-research

breaking pplx-7b-online, pplx-70b-online, pplx-7b-chat, pplx-70b-chat all deprecated and removed. These were the original Perplexity model names. ↓

fix Migrate to sonar (lightweight) or sonar-pro (advanced)

breaking R1-1776 removed Aug 1, 2025. ↓

fix Use sonar-reasoning-pro (powered by DeepSeek-R1 with stronger performance)

deprecated After April 18, 2025: citation tokens and search result counts no longer returned in usage field for Sonar Pro and Sonar Reasoning Pro. ↓

fix Do not rely on usage.citations or usage.search_results_count — these fields removed from API response

gotcha pip install package is perplexityai but the module you import from is perplexity. These are different names — a common confusion source. ↓

fix pip install perplexityai, then from perplexity import Perplexity

gotcha Env var is PERPLEXITY_API_KEY. Some third-party docs incorrectly show PPLX_API_KEY (legacy curl examples) or PERPLEXITYAI_API_KEY. Only PERPLEXITY_API_KEY is auto-read by the SDK. ↓

fix export PERPLEXITY_API_KEY=your_key

gotcha sonar-deep-research is async by design — responses can take minutes. Do not use with short timeouts. Supports reasoning_effort: low/medium/high parameter. ↓

fix Set httpx timeout to 300+ seconds for deep research. Use stream=True to get incremental output.

Install

pip install openai

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) openai - - - -

3.10 alpine (musl) perplexityai - - 0.82s 33.3M

3.10 slim (glibc) openai - - - -

3.10 slim (glibc) perplexityai - - 0.59s 33M

3.11 alpine (musl) openai - - - -

3.11 alpine (musl) perplexityai - - 1.13s 36.5M

3.11 slim (glibc) openai - - - -

3.11 slim (glibc) perplexityai - - 0.95s 36M

3.12 alpine (musl) openai - - - -

3.12 alpine (musl) perplexityai - - 1.28s 27.9M

3.12 slim (glibc) openai - - - -

3.12 slim (glibc) perplexityai - - 1.28s 28M

3.13 alpine (musl) openai - - - -

3.13 alpine (musl) perplexityai - - 1.18s 27.6M

3.13 slim (glibc) openai - - - -

3.13 slim (glibc) perplexityai - - 1.14s 27M

3.9 alpine (musl) openai - - - -

3.9 alpine (musl) perplexityai - - 0.78s 32.7M

3.9 slim (glibc) openai - - - -

3.9 slim (glibc) perplexityai - - 0.79s 32M

Imports

Perplexity
wrong
```
import perplexityai
```
correct
```
from perplexity import Perplexity
```
Package installs as perplexityai but module name is perplexity

AsyncPerplexity

wrong

from perplexityai import AsyncPerplexity

correct

from perplexity import AsyncPerplexity

Same pattern — import from perplexity, not perplexityai

Quickstart verified last tested: 2026-05-12

Web-grounded chat completion with citations

from perplexity import Perplexity

client = Perplexity()  # reads PERPLEXITY_API_KEY automatically

response = client.chat.completions.create(
    model='sonar',
    messages=[{'role': 'user', 'content': 'What happened in AI this week?'}]
)
print(response.choices[0].message.content)