FastAPI CLI: Dev, Run, and Deploy Without the Bloat

You've built a FastAPI app. Now what? If you're still typing uvicorn main:app --reload like it's 2019, you're wasting time and missing production-ready defaults. I've seen teams deploy with --reload still on because they copy-pasted the dev command. That's a memory leak waiting to happen.

The FastAPI CLI exists because the community needed a single, opinionated tool that handles dev, run, and deploy without the guesswork. It's not just a wrapper—it sets sane defaults for workers, reload, and environment detection. No more if DEBUG hacks in your entry point.

By the end of this, you'll be able to scaffold a new project, run it in dev with hot reload, deploy it in production with correct worker counts, and debug the most common failures—all from the CLI. No Dockerfile required for basic deployments.

Why FastAPI CLI Exists: The Problem with Raw Uvicorn

Before FastAPI CLI, every project had a run.py that looked like a frankenstein of environment checks, reload flags, and port bindings. You'd see uvicorn.run(app, host='0.0.0.0', port=int(os.getenv('PORT', 8000)), reload=os.getenv('ENV')=='dev'). That's boilerplate that shouldn't exist.

The CLI eliminates this. It knows that fastapi dev means reload on, debug on, single worker. fastapi run means reload off, multiple workers, production logging. No more accidental --reload in prod. No more forgetting to set --host 0.0.0.0 and wondering why Docker port mapping fails.

But here's the catch: the CLI is opinionated. It assumes your app is in a file called main.py with a variable app. If you named your file server.py or your variable api, you need to specify: fastapi dev server.py or fastapi dev main:api. The CLI will try to auto-detect, but don't rely on it.

# io.thecodeforge — Python tutorial

from fastapi import FastAPI

app = FastAPI()

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

Development Workflow: Hot Reload That Actually Works

The dev command is where FastAPI CLI shines. Run fastapi dev main.py and you get: - Auto-reload on any .py file change (not just the entry point) - Debug mode enabled (full tracebacks in responses) - Single worker (no concurrency surprises) - Host bound to 127.0.0.1 by default (safe for local dev)

But there's a nuance: the reload watches the entire directory tree. If you have a node_modules or a giant data/ folder, the watcher will thrash. I've seen this bring down a dev server on a monorepo because the file watcher exhausted inotify watches. Fix: exclude directories with --reload-dir or better, keep your project structure clean.

Another gotcha: if you're using Docker for local dev, fastapi dev inside a container won't reload because file changes on the host don't propagate to the container's filesystem unless you mount volumes correctly. Use docker compose with a volume mount and set --reload-dir /app.

# io.thecodeforge — Python tutorial

# Start dev server with reload
fastapi dev main.py

# With custom host and port
fastapi dev main.py --host 0.0.0.0 --port 8080

# Exclude a directory from reload
fastapi dev main.py --reload-dir . --reload-exclude 'data/*'

Production Serving: Workers, Graceful Shutdown, and Logging

The worker count is critical. The classic rookie mistake: setting --workers to the number of CPU cores. That's fine for CPU-bound tasks, but FastAPI apps are I/O-bound (waiting on databases, APIs). You want more workers to overlap I/O. Rule of thumb: 2 * CPU cores + 1. But memory is the real constraint. Each worker is a separate process with its own memory. On a 1GB container, 4 workers might OOM under load.

Graceful shutdown is another hidden gem. When you send SIGTERM to the master process, it stops accepting new connections and waits for existing requests to finish (up to a timeout). This prevents dropped requests during deploys. But if your workers are stuck on long-running tasks, they'll be killed after the timeout. Use --timeout-keep-alive to control this.

# io.thecodeforge — Python tutorial

# Production run with 4 workers
fastapi run main.py --workers 4

# With custom port and timeout
fastapi run main.py --port 80 --timeout-keep-alive 30

# Behind a reverse proxy, bind to 127.0.0.1
fastapi run main.py --host 127.0.0.1 --port 8000

Environment Management: .env Files and Configuration

FastAPI CLI automatically loads .env files if they exist. This is huge. No more python-dotenv boilerplate. The CLI reads .env from the current directory and exports variables before starting the app. This means os.getenv('DATABASE_URL') just works.

But there's a subtlety: the CLI loads .env only if you don't set the environment variable yourself. So if you have DATABASE_URL in both .env and the shell environment, the shell wins. This is correct behavior—it allows Docker or CI to override local settings.

Another trap: the CLI does NOT load .env for fastapi dev if you're using a different working directory. Always run the command from the project root. Or use --env-file to specify a path: fastapi dev main.py --env-file config/.env.prod.

# io.thecodeforge — Python tutorial

# .env file content:
DATABASE_URL=postgresql://user:pass@localhost/db
SECRET_KEY=supersecret

# FastAPI CLI loads it automatically
fastapi dev main.py

# Or specify a custom env file
fastapi run main.py --env-file .env.production

Scaffolding: fastapi new and Project Structure

The fastapi new command generates a project skeleton. It's not just a hello world—it creates a proper structure with main.py, routers/, models/, schemas/, and a requirements.txt. This is gold for teams that want consistency.

But here's the honest truth: I rarely use it. The generated structure is fine for a microservice, but if you're building a monolith or a library, it's overkill. Also, it pins FastAPI to the latest version, which can cause dependency conflicts if you're in a monorepo. Use it for greenfield projects, but don't feel bad about rolling your own.

One thing it does well: it creates a Dockerfile that uses fastapi run as the entry point. That's a solid default. But it uses python:3.11-slim which might be too heavy for some deployments. Swap to python:3.11-alpine if you're size-conscious.

# io.thecodeforge — Python tutorial

# Create a new project
fastapi new my_project

# This creates:
# my_project/
# ├── app/
# │   ├── __init__.py
# │   ├── main.py
# │   ├── routers/
# │   │   └── __init__.py
# │   ├── models/
# │   │   └── __init__.py
# │   └── schemas/
# │       └── __init__.py
# ├── Dockerfile
# ├── requirements.txt
# └── .env

Deployment: Docker, Kubernetes, and Process Managers

The CLI is not a deployment tool—it's a server runner. For production, you still need a process manager to keep it alive. The simplest: use fastapi run inside a Docker container with CMD ["fastapi", "run", "main.py", "--workers", "4"]. Then use Docker's restart policy or Kubernetes liveness probes.

But if you're not using containers, you need something like Supervisor or systemd. The CLI doesn't daemonize—it runs in the foreground. That's correct for containers, but for bare metal, you'll want a service file. Here's a systemd unit that works:

``` [Unit] Description=FastAPI app After=network.target

[Service] User=www-data WorkingDirectory=/opt/myapp ExecStart=/usr/local/bin/fastapi run main.py --workers 4 Restart=always

[Install] WantedBy=multi-user.target ```

One more thing: never run fastapi run as root. Create a dedicated user. The CLI doesn't enforce this, but it's a security risk.

# io.thecodeforge — Python tutorial

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["fastapi", "run", "main.py", "--workers", "4", "--port", "8000"]

Debugging Common CLI Failures

Let's talk about the errors that will hit you at 2am.

Error: ModuleNotFoundError: No module named 'app' You ran fastapi dev from the wrong directory. The CLI looks for main.py in the current directory. If your app is in src/main.py, run fastapi dev src/main.py.

Error: Address already in use Another process is on that port. Use lsof -i :8000 to find it, then kill -9 <PID>. Or change the port with --port.

Error: Workers dying with Segmentation fault This is almost always a C extension incompatibility. Check if you're using orjson or uvloop with an incompatible Python version. Downgrade or upgrade the library.

# io.thecodeforge — Python tutorial

# Find what's using port 8000
lsof -i :8000

# Increase file descriptor limit
ulimit -n 65536
fastapi run main.py --workers 4

# Run with verbose logging
fastapi run main.py --log-level debug

# io.thecodeforge — Python tutorial

# When you need custom Uvicorn options
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4 --limit-concurrency 100 --backlog 2048

# With Gunicorn
gunicorn -k uvicorn.workers.UvicornWorker main:app --bind 0.0.0.0:8000 --workers 4