Back to Knowledge
Updated Sep 2026

Vibe Coding with Python

Python people can vibe code too. Here's the modern Python toolkit (uv, FastAPI or Django, Postgres), how to wire up auth the way the FastAPI docs do it today, and where to deploy, including right next to your Next.js frontend on Vercel.

1Django vs FastAPI: Which Framework?

Python has two excellent web frameworks. Pick based on what you're building, not what's 'better.'

Django

Django

Python's batteries-included web framework. Comes with admin panel, ORM, authentication, and forms out of the box. Fast to prototype, scales to production.

"Like a Swiss Army knife for Python web apps. Everything you need is already attached."

 (Full-Stack Framework)

Strengths

  • • Batteries included (admin, auth, ORM, migrations)
  • • Great for full-stack, server-rendered apps
  • • Mature ecosystem with 20 years of answers online
  • • Excellent documentation
  • • Sensible security defaults (CSRF, XSS escaping)

Trade-offs

  • • Heavier and more opinionated
  • • Overkill for a small JSON API
  • • Async support exists but most of the ecosystem is sync

Best for: Full-stack apps, admin panels, content sites, and projects where you want everything in the box.

FastAPI

FastAPI

Modern Python framework for building APIs. Automatic API docs, type hints, async support, and blazing fast performance. Great for AI assistants to work with.

"Like Django's younger, faster sibling. Focuses on APIs and does them really well."

 (Modern API Framework)

Strengths

  • • Async-native and fast
  • • Auto-generated interactive API docs at /docs
  • • Validation from type hints (Pydantic)
  • • Minimal boilerplate
  • • Natural fit for AI and ML endpoints

Trade-offs

  • • No built-in admin panel
  • • You choose your own ORM and auth
  • • More decisions for you (or Claude) to make

Best for: APIs, microservices, AI/ML model serving, and backends for a Next.js or mobile frontend.

Vibe Stack

For API-first apps: FastAPI is the vibe. It's fast, modern, and Claude Code

Claude Code

Anthropic's agentic coding tool. It lives in your terminal (and in VS Code, JetBrains, and on the web), reads your codebase, edits files, runs commands, and ships code. Install with the native installer (`curl -fsSL https://claude.ai/install.sh | bash` on macOS/Linux, `irm https://claude.ai/install.ps1 | iex` on Windows); it needs a Pro, Max, Team, Enterprise, or Console account.

"Like having a senior developer living in your terminal, ready to help 24/7."

is very comfortable in it because the type hints tell it exactly what every function expects.

For full-stack apps: Django is still excellent. The built-in admin alone saves weeks.

2Use uv, Not pip + venv

uv

uv (Python)

A very fast Python package and project manager from Astral that replaces pip, virtualenv, and friends with one tool. Typical flow: `uv init`, `uv add <package>`, `uv run main.py`; it creates and manages the virtual environment for you.

"Like npm for Python, but it also sets up the kitchen (virtual environment) before you start cooking."

is the modern default for Python projects. One tool replaces pip, venv, pip-tools, and pyenv: it creates the virtual environment for you, installs Python if you don't have it, writes a lockfile, and is dramatically faster. Think of it as npm for Python. It's also what the FastAPI docs and Anthropic's Python quickstarts now show first.

Install uv (macOS / Linux)

curl -LsSf https://astral.sh/uv/install.sh | sh

Install uv (Windows PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Already use Homebrew or pipx? brew install uv or pipx install uv work too.

The whole project workflow

uv init my-api          # creates pyproject.toml, .python-version, main.py
cd my-api
uv add "fastapi[standard]"   # adds the dependency + writes uv.lock
uv run main.py           # runs inside the project's .venv automatically

Old way

python -m venv venv, remember to activate it, pip install, then pip freeze > requirements.txt and hope versions match on the server.

uv way

uv add and uv run. No activation step, and uv.lock pins exact versions so your laptop and your deploy match.

Tell your AI: Add "use uv for all dependency and run commands" to your CLAUDE.md

CLAUDE.md

A Markdown file Claude Code reads at the start of every session: project context, commands, conventions, and rules. Put it at `./CLAUDE.md` (shared with the team), `~/.claude/CLAUDE.md` (personal, all projects), or `CLAUDE.local.md` (personal, gitignored). Run `/init` to generate a starter; AGENTS.md is read too.

"Like a welcome packet for a new team member. It tells Claude everything it needs to know about your project."

. Otherwise assistants often fall back to pip install and you end up with packages outside your project environment.

3Recommended Python Stack

Framework: FastAPI or Django

Choose based on your project type (see above)

Terminal

uv add "fastapi[standard]"   # FastAPI + uvicorn + the fastapi CLI
# or
uv add django

Database: PostgreSQL

PostgreSQL

A powerful, open-source relational database. Rock-solid, feature-rich, and the choice for serious production apps.

"Like the Toyota Camry of databases. Reliable, well-documented, handles anything you throw at it."

 via Neon

Neon

Serverless PostgreSQL. It auto-scales, scales to zero when idle, branches like Git, and has a free tier (as of Sep 2026). You can provision it straight from the Vercel Marketplace. Perfect for vibe coding.

"Like PostgreSQL that wakes up when you need it and sleeps when you don't. Pay for what you use."

Same database the JavaScript Vibe Stack uses, serverless-ready

Why PostgreSQL

  • • Django's ORM loves it
  • • SQLAlchemy 2.0 works perfectly
  • • JSON columns for flexible data
  • • Modern driver: psycopg 3 (package name psycopg)

Why Neon

  • • Free tier with scale-to-zero
  • • Instant database branching
  • • Built-in connection pooling
  • • Works with Django and FastAPI

Terminal

uv add sqlalchemy "psycopg[binary]"

Driver gotcha: psycopg is psycopg 3. psycopg2 / psycopg2-binary is the old v2 package, so don't mix them. With SQLAlchemy, point it at psycopg 3 using a postgresql+psycopg:// URL. More on picking a host in Databases and Neon.

Authentication

Multiple options depending on framework

Django: built-in auth system

Django ships user management, sessions, and password hashing. Add django-allauth for social logins.

FastAPI: PyJWT + pwdlib (Argon2)

The FastAPI security tutorial now uses pyjwt for JWTs

JWT (JSON Web Token)

A compact, secure way to transmit information between parties. Often used for authentication tokens after login.

"Like a tamper-proof wristband at a concert. Shows you're allowed in without checking the list every time."

and pwdlib[argon2] for password hashing. Older tutorials (and older AI answers) use python-jose and passlib; skip those for new code.

Terminal

uv add pyjwt "pwdlib[argon2]"

security.py

from datetime import datetime, timedelta, timezone
import os

import jwt
from jwt.exceptions import InvalidTokenError
from pwdlib import PasswordHash

SECRET_KEY = os.environ["JWT_SECRET"]  # generate with: openssl rand -hex 32
ALGORITHM = "HS256"
password_hash = PasswordHash.recommended()  # Argon2

def hash_password(password: str) -> str:
    return password_hash.hash(password)

def verify_password(plain: str, hashed: str) -> bool:
    return password_hash.verify(plain, hashed)

def create_access_token(sub: str, minutes: int = 30) -> str:
    expire = datetime.now(timezone.utc) + timedelta(minutes=minutes)
    return jwt.encode({"sub": sub, "exp": expire}, SECRET_KEY, algorithm=ALGORITHM)

def read_token(token: str) -> str | None:
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        return payload.get("sub")
    except InvalidTokenError:
        return None

Both: a hosted auth provider

Clerk, Auth0, and similar services have Python SDKs if you'd rather not own password storage at all. See Auth for how to choose.

Deployment: Vercel, Railway, or Render

All three deploy from GitHub; they differ in how your app runs

Vercel

  • • FastAPI, Flask, and Django run as Vercel Functions on Fluid Compute

    Fluid Compute

    Vercel's default function runtime model (on for new projects since April 2025). Instead of one request per function instance, an instance can handle many requests at once, keep working after the response with `waitUntil`, and you're billed for active CPU time rather than time spent waiting on things like AI responses.

    "Like a waiter who serves several tables at once instead of standing idle while one table's food cooks."

  • • Python 3.12 (default), 3.13, 3.14
  • • Reads pyproject.toml + uv.lock
  • • Best when your frontend is already on Vercel

Railway

  • • Long-running servers and workers
  • • One-time trial credit, then a small free plan or paid Hobby plan
  • • Easy Postgres/Redis add-ons

Render

  • • Free web services spin down after 15 min idle
  • • Free Postgres expires 30 days after creation
  • • Fine for demos; pay before real users arrive

Free tiers change. Check Railway pricing and Render's free-tier docs before you commit. Also worth a look: Fly.io or Google Cloud Run (if you're comfortable with Docker

Docker

A tool that packages your app and its environment into a 'container' that runs the same everywhere. No more 'it works on my machine.'

"Like shipping furniture in a box. Everything arrives exactly as it was packed."

).

4Vibe Coding with Python + AI

Claude Code works excellently with Python. A few habits make it dramatically better.

Type hints are your friend

Claude understands your code better with type hints. Use them everywhere, especially with FastAPI and Pydantic.

Good: Claude knows exactly what you want

def get_user(user_id: int) -> User | None:
    return db.get(User, user_id)

Write the rules down in CLAUDE.md

A few lines stop the most common Python mix-ups before they happen:

CLAUDE.md

## Python conventions
- Use uv: `uv add <pkg>`, `uv run <cmd>`. Never call pip directly.
- Python 3.12+. Type hints on every function.
- DB driver is psycopg 3 (`psycopg`), not psycopg2.
- Auth uses pyjwt + pwdlib[argon2], not python-jose/passlib.
- Run tests with: uv run pytest

Ask for modern Python

Be explicit about versions. Example prompt: "Use FastAPI with async SQLAlchemy 2.0 and psycopg 3, Python 3.12 features, and Pydantic models for every request and response."

Project structure matters

Claude works best with a predictable layout:

Project layout

my-api/
├── app/
│   ├── main.py          # FastAPI app (app = FastAPI())
│   ├── models.py        # Database models
│   ├── routes/          # API endpoints
│   └── services/        # Business logic
├── tests/
├── pyproject.toml       # managed by uv
├── uv.lock              # commit this
├── .python-version
└── CLAUDE.md

5Common Python App Patterns

Pattern 1: FastAPI backend + Next.js frontend

Build the API in FastAPI and the UI in Next.js. You can host both on Vercel in one project, or put the API on Railway/Render if it needs to run long background jobs.

FastAPI backendNext.js frontendNeon database

Pattern 2: Full-stack Django + HTMX

Django templates plus HTMX for dynamic bits. No separate frontend framework, no API layer to design. Ship fast.

Django + templatesHTMX for reactivityAlpine.js for sprinkles

Pattern 3: AI / ML endpoint with FastAPI

FastAPI is a natural home for model serving and LLM calls. Streaming responses work, and Python gets first-class SDKs from every AI lab. Building agents in Python? The Claude Agent SDK installs with uv add claude-agent-sdk.

FastAPIscikit-learn / PyTorchLLM SDKs

Pattern 4: Django REST Framework for mobile apps

Django + DRF makes a sturdy API for an Expo / React Native app. Pair with Building for iOS.

Django + DRFToken or JWT authMobile clients

6Quick Start: FastAPI + Neon + Vercel

1

Create the project

Terminal

uv init my-api
cd my-api
uv add "fastapi[standard]" sqlalchemy "psycopg[binary]"
2

Create a Neon database

Create a free project at neon.com and copy the connection string into a .env file as DATABASE_URL (an environment variable

Environment Variable

A secret value stored outside your code, like API keys or passwords. Keeps sensitive info out of your codebase.

"Like a sticky note with the WiFi password — you know it, but you don't write it on the wall."

, never hard-coded). Walkthrough: Connect a Database.

3

Write your first endpoint

main.py

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello World"}

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}
4

Run it locally

Terminal

uv run fastapi dev main.py

Open http://localhost:8000/docs for the auto-generated, clickable API docs.

5

Deploy

Push to GitHub and import the repo in Vercel, or deploy from the CLI. Vercel finds app in main.py automatically. Add DATABASE_URL in the project's environment variables (see Environment Variables).

Terminal

vercel deploy

Prefer a long-running server? Railway and Render both detect Python projects from GitHub; set the start command to uv run fastapi run main.py.

Your API is live. FastAPI serves interactive docs at /docs. Share that URL with whoever builds the frontend (probably also you, with Claude).

7Common Traps

Installing outside the project

Running pip install globally (or letting your AI do it) means the package isn't in uv.lock and your deploy breaks. Use uv add, always.

Mixing psycopg2 and psycopg

They're different packages with different URL schemes in SQLAlchemy. Pick psycopg 3 and use postgresql+psycopg:// URLs.

Copying old auth tutorials

python-jose and passlib show up in years of blog posts. The current FastAPI docs use pyjwt and pwdlib[argon2].

Trusting a free tier with real data

Render's free Postgres expires after 30 days and free web services sleep when idle. Great for demos, not for customers.

Committing secrets

JWT secrets and DATABASE_URL live in .env locally (gitignored) and in your host's environment settings in production.

Ready to vibe code with Python?

Python + uv + an AI assistant = shipping quality code fast. Next, learn how to steer the assistant itself.

FastAPI Docs uv Docs Claude Code Tips