Install & Compatibility
Where this runs
tested against v0.43.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.774s · 33.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.7s · import 1.626s · 33MB
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Perplexity
✓ from perplexity import Perplexity
✗ import perplexityai
Package installs as perplexityai but module name is perplexity
AsyncPerplexity
✓ from perplexity import AsyncPerplexity
✗ from perplexityai import AsyncPerplexity
Same pattern — import from perplexity, not perplexityai
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)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'perplexity'
The `perplexityai` Python package is not installed in your current environment.
fixInstall the package using pip: `pip install perplexityai`
perplexity.AuthenticationError: Invalid API key.
The API key provided is either missing, incorrect, or expired, leading to authentication failure.
fixEnsure 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")`
400 'messages' is a required property.
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.
fixProvide a list of message dictionaries, each with a 'role' (e.g., 'user', 'assistant') and 'content' key. Example: `messages=[{"role": "user", "content": "Hello!"}]` 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}}
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.
fixUse 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.
AttributeError: 'str' object has no attribute 'choices'
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).
fixImplement 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.
Upgrade
Version history
0.43.3latest on PyPI · released Aug 11, 2026
Audit
Dependencies
No dependency data recorded yet.