Install & Compatibility
Where this runs
tested against v3.0.0 · 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
py 3.10
✕ build_error
2/4 runs
py 3.11
✕ build_error
2/4 runs
py 3.12
✕ build_error
✕ build_error
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
2/4 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pai
✓ import pandasai as pai
✗ from pandasai import PandasAI
For PandasAI v3, `pandasai` should be imported as `pai` and its functions like `pai.DataFrame` or `pai.Agent` should be used. `PandasAI` class from v2 is deprecated.
LiteLLM
✓ from pandasai_litellm.litellm import LiteLLM
✗ from pandasai.llm.openai import OpenAI
In v3, LLMs are extension-based. LiteLLM is the recommended unified interface. Direct LLM imports like `pandasai.llm.openai.OpenAI` from v2 no longer work.
This quickstart demonstrates how to initialize PandasAI v3 with LiteLLM for conversational data analysis on a pandas DataFrame. It includes setting up the LLM globally and using the `pai.DataFrame` wrapper to query data in natural language.
import os
import pandas as pd
import pandasai as pai
from pandasai_litellm.litellm import LiteLLM
# Set your API key from environment variable
openai_api_key = os.environ.get('OPENAI_API_KEY', 'YOUR_OPENAI_API_KEY')
# Initialize LiteLLM with your desired model
# Ensure the model name is correct and supported by your LiteLLM setup/API key
llm = LiteLLM(model="gpt-4o-mini", api_key=openai_api_key)
# Configure PandasAI globally with the LLM
pai.config.set({"llm": llm})
# Sample DataFrame
data = {
"country": ["United States", "United Kingdom", "France", "Germany", "Italy", "Spain"],
"gdp": [19294482071552, 2891615567872, 2411255037952, 3435817336832, 1745433788416, 1181205135360],
"happiness_index": [6.94, 7.16, 6.66, 7.07, 6.38, 6.4]
}
df = pd.DataFrame(data)
# Convert pandas DataFrame to PandasAI DataFrame
pai_df = pai.DataFrame(df)
# Chat with your data
response = pai_df.chat("Which are the top 3 countries by GDP?")
print(response)
pandasai --version
Debug
Known issues
breakingPandasAI v3 introduces significant architectural changes, particularly in how LLMs are configured and imported. LLMs are now extension-based, requiring separate installations like `pandasai-litellm`. The LLM must be configured globally using `pai.config.set()` instead of being passed directly to `SmartDataframe` or `Agent` constructors.fixInstall `pandasai-litellm` and update LLM import paths. Use `pai.config.set({'llm': your_llm_instance})` for global LLM configuration. Refer to the official migration guide for v2 to v3. affects: 3.0.0-alpha to 3.x.x (from v2.x.x)
breakingThe `SmartDataframe` and `SmartDatalake` classes from v2 are largely superseded by a new API pattern in v3. While `SmartDataframe` may still work for single dataframes, the recommended approach is `pai.DataFrame()`. `SmartDatalake` is no longer necessary, as `pai.chat()` can query multiple dataframes directly. Also, methods like `push()` and `pull()` on DataFrames were removed in v3.0.0.fixMigrate to `pai.DataFrame()` for single dataframes and use `pai.chat()` directly for multiple dataframes. Avoid using `push()` or `pull()` methods.
affects: 3.0.0-alpha to 3.x.x (from v2.x.x)
breakingSeveral utility methods on the `Agent` class, such as `clarification_questions()`, `rephrase_query()`, and `explain()`, have been removed in v3.fixThese methods no longer exist. For conversational flow, rely on the `agent.chat()` and `agent.follow_up()` methods, which maintain context automatically.
affects: 3.0.0-alpha to 3.x.x (from v2.x.x)
gotchaPandasAI currently specifies Python requirements as `<3.12,>=3.8` and may pin `pandas==1.5.3`. This can lead to installation failures or unexpected behavior if attempting to install with Python 3.12+ or if another package in your environment requires a newer `pandas` version (e.g., Pandas 3.0+ has significant breaking changes like Copy-on-Write semantics and dedicated string dtypes, which are incompatible with `pandasai`'s pinned version).fixUse a Python environment with version 3.8 to 3.11. If encountering build errors, consider installing `pandas==1.5.3` manually before installing `pandasai`, or use `conda install pandas=1.5.3` if in a Conda environment. Avoid using Pandas 3.0+ with current PandasAI versions.
affects: All versions up to 3.0.0
gotchaLLM model drift (changes in underlying LLM behavior over time) can cause previously working queries to fail or produce incorrect Python code (e.g., type mismatches, inappropriate method calls) during execution by PandasAI. This is particularly noted with OpenAI models.fixUse explicit type hints in your prompts to guide the LLM. Implement a code validation layer before execution if possible. Consider pinning specific LLM model versions where supported. Log the generated Python code to identify failure patterns.
affects: All versions
Upgrade
Version history
3.0.0latest on PyPI · released Oct 7, 2025
Audit
Dependencies
pythonrequiredRequired Python version range.
pandasrequiredCore data manipulation library; PandasAI is built on top of it.
pandasai-litellmoptionalRecommended extension for unified LLM access (e.g., OpenAI, Google PaLM, Anthropic, VertexAI) in v3.
openaioptionalNeeded for direct OpenAI LLM integration (older v2 pattern or if not using LiteLLM).