Install Vanna AI 2.0.2 for Natural Language to SQL

Analysts still queue on whoever can write SQL. Natural language to SQL is supposed to end that – if the stack actually installs. Vanna AI 2.0.2 is the open-source Agent/FastAPI line you can self-host for it. This guide is deployment-first: pin, configure, verify, and fix the post-archive footguns. Not another 0.x vn.ask() walkthrough.

v2.0 rewrote the product around a user-aware Agent, tools, streaming UI, and FastAPI/Flask servers. 2024 copy-paste imports break. Concrete deploy steps below, current as of early 2026.

System requirements before you touch pip

PyPI owns the runtime constraint. The quickstart still mentions Python 3.8+; the published package sets requires-python >=3.9. Install on 3.8 and the resolver refuses the wheel.

Wheel pulls pydantic 2.x, pandas, httpx, SQLAlchemy, sqlparse, plotly, click, PyYAML, tabulate, requests. Drivers and LLM SDKs sit behind extras: postgres, mysql, anthropic, openai, fastapi, flask, ollama, chromadb, all.

Funny part: most “text-to-SQL failed” threads aren’t model quality. They’re a Saturday lost to the wrong package metadata while the warehouse query never even ran. Fix the floor first.

Where to get Vanna for natural language to SQL

Latest stable on PyPI is 2.0.2 (2 Feb 2026). Docs live at vanna.ai/docs. The GitHub repo (vanna-ai/vanna, ~23.8k stars) went read-only on 29 Mar 2026 – grab historical tags and the migration guide there, but don’t wait on fresh triage.

Sample DB from the official 5-minute path:

curl -o Chinook.sqlite https://vanna.ai/Chinook.sqlite

Install Vanna AI 2.0.2 step by step

Fresh venv. Pin the version. Community thread GitHub issue #1025 is the reason: bare vanna[anthropic,fastapi] can resolve into a broken 0.1.0-shaped install with vanna.servers missing.

python3 -m venv vanna-env
source vanna-env/bin/activate # Windows: vanna-envScriptsactivate
pip install -U pip

# Pin explicitly - recommended path
pip install "vanna[fastapi,anthropic]==2.0.2"

# Trust packaging metadata over import __version__
pip show vanna

You want Version: 2.0.2 from pip show. Some builds still carry an internal __version__ = "0.1.0" string in source. That’s why python -c "import vanna; print(vanna.__version__)" alone lies to people.

If PyPI resolution still wobbles: install the 2.0.2 wheel from PyPI files, or a git tag pin such as pip install "vanna[fastapi,anthropic] @ git+https://github.com/vanna-ai/[email protected]". Prefer a clean PyPI 2.0.2 when pip show agrees.

Pro tip:pip show vanna right after install. Version starts with 0.? Uninstall and reinstall with ==2.0.2 before you chase imports for an hour.

First-time configuration (minimum viable agent)

Pattern matches the official Agent quickstart – SQLite + Anthropic + FastAPI UI (5-minute quickstart):

# app.py
import os
from vanna import Agent, AgentConfig
from vanna.servers.fastapi import VannaFastAPIServer
from vanna.core.registry import ToolRegistry
from vanna.core.user import CookieEmailUserResolver
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.tools import RunSqlTool
from vanna.integrations.sqlite import SqliteRunner
from vanna.integrations.local.agent_memory import DemoAgentMemory

tools = ToolRegistry()
tools.register_local_tool(
 RunSqlTool(sql_runner=SqliteRunner(database_path="./Chinook.sqlite")),
 access_groups=["users"],
)

agent = Agent(
 llm_service=AnthropicLlmService(
 model="claude-sonnet-4",
 api_key=os.environ["ANTHROPIC_API_KEY"],
 ),
 tool_registry=tools,
 user_resolver=CookieEmailUserResolver(),
 agent_memory=DemoAgentMemory(max_items=1000),
 config=AgentConfig(),
)

if __name__ == "__main__":
 server = VannaFastAPIServer(agent)
 server.run() # http://localhost:8000

Set the key, start the process:

export ANTHROPIC_API_KEY=sk-ant-...
python app.py

Open http://localhost:8000, sign in with any email the cookie resolver accepts (e.g. [email protected]), ask: “What tables are in this database?”

Production means your own JWT/cookie UserResolver, real Postgres/MySQL runners, and auth in front of chat routes. MIT self-host stays free. Hosted admin examples on their pricing page: Explorer ~$50/mo, Team ~$500/mo, Enterprise custom – confirm live rates before you budget (as of the published tiers on app.vanna.ai/pricing).

Verify the install actually works

1. pip show vanna → Version 2.0.2
2. python -c "from vanna.servers.fastapi import VannaFastAPIServer; print('ok')"
3. Process listens on http://localhost:8000
4. Browser UI loads; a natural-language question returns SQL plus table/streamed pieces

Blank UI? Read the terminal. Port 8000 already taken is the boring answer – bind another port on server.run(...) and move on. Remember the pin: if step 2 can’t import vanna.servers, you’re not debugging FastAPI yet.

When the demo finally answers in plain English, who on your team is allowed to trust that SQL against production data – and who only gets a read replica? Worth deciding before the UI feels “done.”

Common install errors and fixes

• ModuleNotFoundError: No module named 'vanna.servers' – bad 0.x-shaped resolve. pip uninstall -y vanna then pip install "vanna[fastapi,anthropic]==2.0.2".
• Python 3.8 environment – fails >=3.9. Upgrade the interpreter.
• pg_config executable not found with vanna[postgres] – psycopg2 build gap. Install libpq dev packages or use a binary wheel path; don’t compile blind on a bare VM.
• Gemini 3 thought_signature 400s – reported on 2.0.1/2.0.2-era GeminiLlmService (issue #1073). First deploy: Anthropic or OpenAI is lower friction.
• Port already in use – change bind port; shared laptops rarely leave 8000 free.

Security caveat: CVE-2026-65702 (CVSS 8.6) describes path traversal in FileSystemConversationStore through 2.0.2 via conversation_id on chat endpoints (Tenable CVE record). Default demo = localhost only. Auth, network policy, and a non-filesystem conversation store before any public URL.

Upgrade from 0.x and uninstall

2.0 isn’t a bump. Different architecture. The migration guide offers LegacyVannaAdapter around an old 0.x object for a quick UI, or a rewrite to Agent + ToolRegistry + runners. vn.train() / vn.ask() do not map 1:1 – that’s why old tutorials strand people on imports.

# Upgrade pin
pip install -U "vanna[fastapi,anthropic]==2.0.2"

# Uninstall / cleanup
pip uninstall -y vanna
deactivate
rm -rf vanna-env
# optional: delete local Chinook.sqlite and DemoAgentMemory files

v2.0.2 itself is a small ChromaDB collection retrieval fix on top of 2.0.1 (#1081). Already healthy on 2.0.x? Routine bump.

FAQ

Is Vanna AI 2.0.2 free for natural language to SQL?

Self-hosted OSS is MIT – yes. You still pay the LLM provider. Vanna’s cloud/admin tiers are separate.

Docker or bare pip – which should I start with?

Hit the wall once on bare metal first. Official quickstart is venv + pip; this guide followed that. When imports and the UI both work, wrap the same app.py in a slim Python 3.11 image, pip install "vanna[fastapi,anthropic]==2.0.2", expose 8000, pass API keys as env. Debugging the extras trap inside Docker layers is how a 20-minute setup becomes an afternoon.

Why did my install say 2.x in one place and 0.1.0 in another?

Extras resolution plus that stale internal version string. Don’t reconcile the two by guessing. pip show vanna plus a clean from vanna.servers.fastapi import VannaFastAPIServer are the only signals that matter. Either fails → pip install --force-reinstall --no-cache-dir "vanna[fastapi,anthropic]==2.0.2". The archived repo won’t rush a metadata patch; pinning is the fix.

Do this next: create the venv, pin vanna[fastapi,anthropic]==2.0.2, drop in app.py with Chinook, and ask one real question on localhost:8000 before you wire production auth.