Installation & Setup

Difficulty: Beginner

Setting up a FastAPI project properly from the start is essential for maintainable development. FastAPI itself is a Python package installed via pip, but a complete development environment requires a few additional tools: an ASGI server to run the application, a virtual environment to isolate dependencies, and a well-organized project structure.

The first step is creating a virtual environment. Python virtual environments create an isolated space for your project's dependencies, preventing conflicts between different projects. You create one with python -m venv venv (the second 'venv' is the directory name - you can choose any name). Activate it with source venv/bin/activate on macOS/Linux or venv\Scripts\activate on Windows. Once activated, your terminal prompt changes to show the environment name, and any pip install commands will install packages only within this environment.

FastAPI requires two main packages: fastapi itself and an ASGI server. The recommended server is Uvicorn, which is a lightning-fast ASGI server built on uvloop (a fast event loop) and httptools (a fast HTTP parser). Install both with pip install fastapi uvicorn. For development, you might also want pip install fastapi[standard] which includes additional useful dependencies like python-multipart for form data, email-validator for email validation, and httpx for testing.

A well-structured FastAPI project typically separates concerns into multiple files and directories. A common layout includes a main.py or app.py as the entry point, a routers/ directory for route modules, a models/ directory for Pydantic models, a database/ directory for database configuration, and a tests/ directory for test files. For small projects, a single main.py file is perfectly fine, but as the project grows, breaking it into modules keeps the code manageable.

To run your FastAPI application during development, use the command uvicorn main:app --reload. Here, 'main' refers to the Python file name (main.py), 'app' refers to the FastAPI instance variable name, and --reload enables auto-reload so the server restarts whenever you change a file. By default, Uvicorn runs on http://127.0.0.1:8000. You can change the host with --host 0.0.0.0 (to accept external connections) and the port with --port 3000.

Dependency management is crucial for reproducible deployments. Always maintain a requirements.txt file listing all your project's dependencies with pinned versions. Generate it with pip freeze > requirements.txt after installing packages. For more sophisticated dependency management, consider using tools like Poetry or pip-tools, which provide dependency resolution and lock files similar to npm's package-lock.json.

Code examples

Project Setup Commands

# Create project directory
mkdir my-fastapi-project
cd my-fastapi-project

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

# Install FastAPI and Uvicorn
pip install fastapi uvicorn

# Or install with all optional dependencies
pip install fastapi[standard]

# Save dependencies
pip freeze > requirements.txt

These shell commands set up a complete FastAPI development environment. The virtual environment ensures dependencies are isolated. The [standard] extra includes commonly used optional dependencies.

Recommended Project Structure

# Small project structure
my-fastapi-project/
  main.py
  requirements.txt
  venv/

# Medium/large project structure
my-fastapi-project/
  app/
    __init__.py
    main.py          # FastAPI app instance
    config.py        # Settings and configuration
    routers/
      __init__.py
      users.py       # User-related endpoints
      items.py       # Item-related endpoints
    models/
      __init__.py
      user.py        # User Pydantic models
      item.py        # Item Pydantic models
    database/
      __init__.py
      connection.py  # DB session setup
      models.py      # SQLAlchemy models
    utils/
      __init__.py
      auth.py        # Authentication helpers
  tests/
    __init__.py
    test_users.py
    test_items.py
  requirements.txt
  .env
  venv/

Small projects can use a single main.py file. As the project grows, separate concerns into routers (endpoints), models (Pydantic schemas), database (ORM models and sessions), and utils (helper functions).

Running the Development Server

# Basic run command
uvicorn main:app --reload

# With custom host and port
uvicorn main:app --reload --host 0.0.0.0 --port 3000

# With logging level
uvicorn main:app --reload --log-level debug

# For a nested app (app/main.py)
uvicorn app.main:app --reload

# Output:
# INFO:     Uvicorn running on http://127.0.0.1:8000
# INFO:     Started reloader process
# INFO:     Started server process
# INFO:     Waiting for application startup.
# INFO:     Application startup complete.

The uvicorn command takes 'module:variable' format. 'main:app' means the 'app' variable in main.py. The --reload flag watches for file changes and restarts automatically, which is essential during development but should not be used in production.

Key points

Concepts covered

pip, Virtual Environments, Uvicorn, Project Structure, Requirements