Text to SQL Open Source: Deploy Vanna AI 2.0 (2026 Guide)

The #1 mistake people make installing Vanna AI right now: they copy pip install vanna[anthropic,fastapi] straight from a blog post – and end up with version 0.1.0 instead of 2.x. None of the 2.0 modules import. Nothing works. They spend an hour debugging.

This isn’t user error. It’s a community-confirmed bug (GitHub issue #1025): the documented pip command sometimes resolves to a stale artifact on PyPI. So let’s reverse-engineer this. If the naive install path is broken, what does a clean, working text to SQL open source deployment of Vanna actually look like in 2026?

What Vanna 2.0 actually is

Vanna started as a thin SQL generation library – RAG over your schema, ask a question, get SQL back. That product is gone. Vanna 2.0 is a complete architectural rewrite into a user-aware agent framework. The old VannaBase mixin pattern? Replaced entirely by an Agent class that tracks user identity per request. Any tutorial from 2024 is wrong for 2.0 – not subtly wrong, but import-fails-on-line-one wrong.

One more thing before you type any commands: the main vanna-ai/vanna repository was archived by the owner on March 29, 2026 and is now read-only (23.7k stars, 2.4k forks – it had a good run). Development continues, but bug reports and PRs on that repo won’t move. Every existing tutorial still links there as if it’s live. It isn’t.

There’s something worth sitting with here. The archival happened just weeks after the 2.0 release – a complete rewrite shipped, then the old repo locked. That’s an unusual sequence. It means the codebase you’re learning today has no patch history on GitHub for anyone to read. The changelog lives in the official docs, not in commits. Keep that in mind when you hit something unexpected and start searching for context.

System requirements

Verified against the PyPI listing published February 2, 2026:

Core dependencies pulled in automatically: pydantic, sqlparse, requests, pyyaml, httpx, click, pandas, plotly, sqlalchemy, tabulate – per the piwheels package listing. RAM and disk requirements aren’t published in official docs; in practice, a local Chroma vector store grows proportionally to how much DDL and example SQL you train on. Start small, measure as you go.

Available extras include: postgres, mysql, snowflake, bigquery, duckdb, anthropic, openai, ollama, chromadb, qdrant, pgvector, milvus, weaviate, and all.

Install the right version (avoid the v0.1.0 trap)

Fresh virtual environment first. Then pin explicitly – don’t trust extras alone to resolve the right major version:

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

# Pin explicitly - do NOT rely on extras alone
pip install "vanna>=2.0,=2.0"

# Verify immediately
python -c "import vanna; print(vanna.__version__)"

If that prints 0.1.0, you hit the bug. Uninstall and install directly from the tagged release on GitHub (check the repo tags first to confirm v2.0.0 exists before running this):

pip uninstall -y vanna
pip install "git+https://github.com/vanna-ai/[email protected]#egg=vanna[anthropic,fastapi]"

Run pip show vanna right after install. If Version: starts with 0., stop and reinstall. Every hour of debugging past that point is wasted.

Think about what just happened there. A version-pinned install of an open-source package can still silently fail because of how pip resolves extras against what’s cached or indexed. The fix isn’t clever – it’s just explicit. Pin the major version. Always. This pattern applies any time you’re pulling a package that had a major API break between versions.

First-time configuration

Grab the demo database, then write a minimal app.py. This mirrors the official quickstart:

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

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="sk-ant-..."
 ),
 tool_registry=tools,
 user_resolver=CookieEmailUserResolver(),
 agent_memory=DemoAgentMemory(),
 config=AgentConfig()
)

server = VannaFastAPIServer(agent)
server.run(host="0.0.0.0", port=8000)

Count those imports. Old tutorials had three lines. This has eight. That’s the Agent API in practice – every component (LLM, SQL runner, user resolver, memory) is injected explicitly rather than mixed in via inheritance. According to the 2.0 README migration section, every component now knows user identity, and the server ships with streaming UI components instead of text and dataframes. If you’re migrating 0.x code, LegacyVannaAdapter wraps your existing instance and gives you the new web UI immediately – that’s the fast path before a full rewrite.

Verify the install works

Run python app.py. Three checks:

1. FastAPI logs Uvicorn running on http://0.0.0.0:8000. No log → import failed, likely the v0.1.0 issue.
2. Visit http://localhost:8000. The built-in <vanna-chat> web component should load – it works with React, Vue, or plain HTML and streams responses via SSE.
3. Type: “How many tracks are in the database?” Expected: SELECT COUNT(*) FROM tracks; plus the result streamed back.

Diagnostics if something’s off. SQL generates but execution fails? Your SQLite path is wrong. SQL never generates? Anthropic key is invalid or rate-limited. Nothing loads at all – port 8000 is taken, try port=8080.

Common errors and real fixes

Every error below comes from actual GitHub issue reports.

• ModuleNotFoundError: No module named ‘vanna.servers’ – You have v0.1.0. See the pinning fix above.
• google.genai.errors.ClientError: 400 INVALID_ARGUMENT – Using Gemini 3? That’s issue #1073. Vanna 2.0.1’s GeminiLlmService fails with Gemini 3 models (gemini-3-flash-preview, gemini-3-pro-preview) because thought_signature handling isn’t implemented. Workaround: downgrade to gemini-2.5-pro or switch to Anthropic until patched.
• Schema awareness errors / wrong SQL on your real DB – Vanna doesn’t read your live schema automatically. You must explicitly train it: agent.train(ddl="CREATE TABLE ..."). This trips up almost every new user.
• pip resolves conflicting deps – Check whether you accidentally installed the vana package (single n). It’s unrelated to Vanna AI. If it’s present, uninstall it.

Upgrading from 0.x, or removing it entirely

Working Vanna 0.x code? Don’t rewrite yet – wrap it. LegacyVannaAdapter is the officially recommended migration path: point your 0.x instance at the new UI and migrate one tool at a time.

To remove Vanna completely:

pip uninstall -y vanna
rm -rf ~/.vanna # persisted training data
rm -rf ./chroma_db # local vector store
deactivate
rm -rf vanna-env

Chroma stores training data on disk by default. If you ran Vanna against a production database and trained it on sensitive schemas, delete that folder – the DDL you fed it lives there in plain text.

Is Vanna the right tool? An honest question before you go further

Most guides skip this. Text-to-SQL accuracy depends almost entirely on training data quality, not on which framework you pick. Vanna, LangChain SQL agent, SQLAI – they all fall apart on complex joins when the vector store has sparse coverage. Before investing days in setup and training, run the Chinook demo successfully, then swap in 5-10 rows of your own DDL and example question/SQL pairs. If answers look right within 30 minutes, invest more. If they don’t, no amount of prompt engineering closes that gap quickly. That’s true of every text-to-SQL tool, but it’s especially true here because the repo is now archived and community support is thin.

FAQ

Is Vanna still maintained if the GitHub repo is archived?

The main repo went read-only on March 29, 2026. The PyPI package still receives releases (latest as of February 2, 2026) and the company continues shipping enterprise features. Community bug reports now route through the official docs and support channels rather than GitHub issues – which means less public visibility into what’s broken. Worth knowing before you depend on it for production.

Can I run Vanna fully locally without sending schema data to OpenAI or Anthropic?

Yes. pip install "vanna[ollama,chromadb]", point OllamaLlmService at Llama 3.1 or Mistral, Chroma handles the vector store on disk. SQL accuracy will be lower than a frontier model – small local models struggle with joins across more than three or four tables. Validate every generated query before running it against real data.

What’s the fastest way to know if Vanna is right for my use case?

Run the Chinook demo first. Then swap in your own DDL and 5-10 example question/SQL pairs and see what you get within 30 minutes. If the answers look right, invest more training data. If they don’t – and this is the part most guides won’t say – the tool won’t improve without a semantic layer or heavy prompt work, and you’d be starting that work against an archived repo with limited community support. That context matters for the decision.

Next step: once the FastAPI server is running, replace SqliteRunner with the runner matching your database – the postgres, snowflake, or bigquery extras each include a corresponding runner class (exact class names are in the official SDK docs, as these may change between patch releases). Training data quality is what determines output quality. Nothing else.