{"id":59,"library":"perplexityai","title":"Perplexity AI Python SDK","description":"Official Python SDK for the Perplexity API — web-grounded chat completions with real-time search, citations, and reasoning.","status":"active","version":"0.30.1","language":"python","source_language":"en","source_url":"https://docs.perplexity.ai","tags":["llm","search","rag","citations","python","openai-compatible"],"install":[{"cmd":"pip install perplexityai","lang":"bash","label":"Official SDK (perplexityai)"},{"cmd":"pip install openai","lang":"bash","label":"OpenAI-compatible alternative"}],"dependencies":[],"imports":[{"note":"Package installs as perplexityai but module name is perplexity","wrong":"import perplexityai","symbol":"Perplexity","correct":"from perplexity import Perplexity"},{"note":"Same pattern — import from perplexity, not perplexityai","wrong":"from perplexityai import AsyncPerplexity","symbol":"AsyncPerplexity","correct":"from perplexity import AsyncPerplexity"}],"quickstart":{"code":"from perplexity import Perplexity\n\nclient = Perplexity()  # reads PERPLEXITY_API_KEY automatically\n\nresponse = client.chat.completions.create(\n    model='sonar',\n    messages=[{'role': 'user', 'content': 'What happened in AI this week?'}]\n)\nprint(response.choices[0].message.content)","lang":"python","description":"Web-grounded chat completion with citations"},"warnings":[{"fix":"Use current Sonar family: sonar, sonar-pro, sonar-reasoning, sonar-reasoning-pro, sonar-deep-research","message":"All llama-3.1-sonar-* and llama-3-sonar-* model names removed Feb 22, 2025. Using them returns a 404/model-not-found error.","severity":"breaking","affected_versions":"all"},{"fix":"Migrate to sonar (lightweight) or sonar-pro (advanced)","message":"pplx-7b-online, pplx-70b-online, pplx-7b-chat, pplx-70b-chat all deprecated and removed. These were the original Perplexity model names.","severity":"breaking","affected_versions":"all"},{"fix":"Use sonar-reasoning-pro (powered by DeepSeek-R1 with stronger performance)","message":"R1-1776 removed Aug 1, 2025.","severity":"breaking","affected_versions":"all"},{"fix":"Do not rely on usage.citations or usage.search_results_count — these fields removed from API response","message":"After April 18, 2025: citation tokens and search result counts no longer returned in usage field for Sonar Pro and Sonar Reasoning Pro.","severity":"deprecated","affected_versions":"all"},{"fix":"pip install perplexityai, then from perplexity import Perplexity","message":"pip install package is perplexityai but the module you import from is perplexity. These are different names — a common confusion source.","severity":"gotcha","affected_versions":"all"},{"fix":"export PERPLEXITY_API_KEY=your_key","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Set httpx timeout to 300+ seconds for deep research. Use stream=True to get incremental output.","message":"sonar-deep-research is async by design — responses can take minutes. Do not use with short timeouts. Supports reasoning_effort: low/medium/high parameter.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T06:16:22.235Z","next_check":"2026-05-28T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install perplexityai`","cause":"The `perplexityai` Python package is not installed in your current environment.","error":"ModuleNotFoundError: No module named 'perplexity'"},{"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\")`","cause":"The API key provided is either missing, incorrect, or expired, leading to authentication failure.","error":"perplexity.AuthenticationError: Invalid API key."},{"fix":"Provide a list of message dictionaries, each with a 'role' (e.g., 'user', 'assistant') and 'content' key. Example: `messages=[{\"role\": \"user\", \"content\": \"Hello!\"}]`","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.","error":"400 'messages' is a required property."},{"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.","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.","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}}"},{"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.","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).","error":"AttributeError: 'str' object has no attribute 'choices'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.82,"mem_mb":16.1,"disk_size":"33.3M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.59,"mem_mb":16.1,"disk_size":"33M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.13,"mem_mb":17.8,"disk_size":"36.5M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.95,"mem_mb":17.8,"disk_size":"36M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.28,"mem_mb":17.7,"disk_size":"27.9M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.28,"mem_mb":17.7,"disk_size":"28M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.18,"mem_mb":18.6,"disk_size":"27.6M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.14,"mem_mb":18.6,"disk_size":"27M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.78,"mem_mb":16.3,"disk_size":"32.7M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.79,"mem_mb":16.3,"disk_size":"32M"}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}