Published on

FastAPI Project Setup: How to Build a Modular Structure

FastAPI allows you to build a production-ready API (Application Programming Interface - a way for different software programs to communicate) in under 10 minutes using Python 3.12+. By using a modular folder structure, you can separate your database logic from your route handlers, making your code easier to maintain as it grows. A standard setup involves creating a virtual environment, installing FastAPI and Uvicorn (a lightning-fast server that runs your code), and organizing files into specific directories like app/, core/, and api/.

Why does folder structure matter for beginners?

When you first start with FastAPI, it is tempting to put all your code in one single file. While this works for a "Hello World" example, it quickly becomes a nightmare to manage as you add more features. A structured approach helps you know exactly where to look when you need to fix a bug or add a new endpoint (a specific URL path that performs a task).

Organizing your code early prevents "spaghetti code," where everything is tangled together. In our experience, spending five minutes setting up a clean directory saves hours of refactoring later. It also makes your project look professional to other developers who might review your work.

What do you need before starting?

Before you write your first line of code, ensure your computer is ready for Python development. You don't need to be an expert, but having these tools installed will make the process much smoother.

  • Python 3.12 or higher: FastAPI takes advantage of the latest Python features for speed and type safety.
  • A Code Editor: VS Code is highly recommended for its excellent Python support.
  • Terminal Access: You will need to run a few commands in your Command Prompt, Terminal, or PowerShell.
  • Basic Terminal Knowledge: You should know how to change directories (cd) and create folders (mkdir).

How do you set up a virtual environment?

A virtual environment is a private sandbox for your project. It ensures that the tools you install for this project don't interfere with other projects on your computer.

Step 1: Create your project folder. Open your terminal and create a new directory for your work.

mkdir my-fastapi-app
cd my-fastapi-app

Step 2: Initialize the virtual environment. Run the following command to create a hidden folder that will hold your project's specific Python version and packages.

python -m venv venv

Step 3: Activate the environment. You must tell your terminal to start using that sandbox.

  • Windows: venv\Scripts\activate
  • Mac/Linux: source venv/bin/activate

What you should see: Your terminal prompt should now show (venv) at the beginning of the line. This means you are safely working inside your isolated environment.

Which packages should you install?

FastAPI needs a few helper tools to function properly. The most important one is an ASGI (Asynchronous Server Gateway Interface - a tool that lets Python handle many web requests at once) server.

You will install fastapi and uvicorn. Uvicorn acts as the engine that runs your FastAPI code so the world can see it.

pip install fastapi uvicorn

What you should see: A list of successfully installed packages in your terminal. You are now ready to start building the file structure.

For a modern FastAPI project in 2026, we recommend a structure that separates your logic into layers. This keeps your main application file clean and easy to read.

Create the following folders and files inside your project:

my-fastapi-app/
├── app/
│   ├── __init__.py
│   ├── main.py          # The entry point of your app
│   ├── api/             # Route handlers (endpoints)
│   │   └── v1/
│   │       └── endpoints/
│   ├── core/            # Configuration and security
│   ├── models/          # Database schemas
│   └── schemas/         # Data validation (Pydantic models)
├── .env                 # Secret keys and settings
└── requirements.txt     # List of your project's tools

Don't worry if this looks like a lot of folders. The __init__.py files are just empty files that tell Python to treat these folders as packages. This allows you to import code from one folder into another easily.

How do you write the "Hello World" code?

Now that your folders are ready, you need to create the main file that starts the server. Navigate to your app/main.py file and add the following code.

from fastapi import FastAPI

# Initialize the FastAPI application
app = FastAPI(title="My First API")

# Define a simple GET route
@app.get("/")
def read_root():
    # Return a simple dictionary that FastAPI converts to JSON
    return {"message": "Hello, your FastAPI project is structured!"}

# This is the starting point for your web server

To run this, go back to your terminal (make sure you are in the root my-fastapi-app folder) and type:

uvicorn app.main:app --reload

What you should see: The terminal will say Uvicorn running on http://127.0.0.1:8000. If you open that link in your browser, you will see your "Hello" message. The --reload flag means the server will automatically restart every time you save a file.

What are common mistakes to avoid?

One common mistake is forgetting to activate the virtual environment before installing packages. If you do this, your computer might use a global version of Python, leading to "ModuleNotFoundError" later. Always check for that (venv) tag in your terminal.

Another mistake is naming your file fastapi.py. This confuses Python because it won't know if you are trying to import the real FastAPI library or your own file.

Finally, beginners often forget to include the __init__.py files in their subfolders. Without these, you won't be able to import your routes or models into main.py. If your code can't find a module you just created, check for that empty file first.

Next Steps

Now that you have a solid foundation, you can start adding more complex features to your project. Try creating a new file in the api/v1/endpoints/ folder and linking it to your main.py using an APIRouter (a tool used to group related routes together). You can also explore how to use Pydantic (a library for data validation) in your schemas/ folder to ensure the data your API receives is correct.

For more detailed guides, visit the official FastAPI documentation.

Read the FastAPI Documentation