Deploy a FastAPI Python App

This guide explains how to deploy a FastAPI (opens in a new tab) Python application to Koyeb using:

  1. Git-driven deployment to automatically build and deploy a new version of your application each time a change is detected on your branch.
  2. Pre-built containers you can deploy from any public or private registry.

To successfully follow this documentation, you will need to have a Koyeb account (opens in a new tab). You can optionally install the Koyeb CLI if you prefer to follow this guide without leaving the terminal.

You can deploy and preview the Python FastAPI application from this guide using the Deploy to Koyeb button below.

Deploy to Koyeb (opens in a new tab)

You can consult the repository on GitHub (opens in a new tab) to find out more about the example application that this guide uses.

Create the Python FastAPI app

Get started by creating a minimalistic Python FastAPI application. You will need Python (opens in a new tab) installed on your machine. In your terminal, run the following commands to create the directory that will hold the application code:

mkdir example-fastapi
cd example-fastapi

Koyeb detects Python applications when one of the Python matching criteria is met. In this guide, we will use a requirements.txt file to trigger the detection.

In the folder you created, create a new virtual environment folder using python -m venv venv. Virtual environments provide isolation from the system environment allowing each virtual environment you create to have its own installation directories, dependencies, etc.

Activate and load your virtual environment by typing:

. venv/bin/activate

Install FastAPI and create a requirements.txt file to store the dependencies and version of each package required to run our application:

pip install fastapi "uvicorn[standard]"
pip freeze > requirements.txt

Next, create a file and copy the following FastAPI application code:
from typing import Union
from fastapi import FastAPI
app = FastAPI()
def read_root():
    return {"message": "Hello from Koyeb"}

The code above defines a single route / that returns a JSON response with the message Hello from Koyeb when a GET / request is made.

Run the Python FastAPI app locally

Launch the application locally to make sure everything is running as expected.

uvicorn main:app --reload

You can now access the application at http://localhost:8000 and the automatic interactive API documentation at http://localhost:8000/docs.

This example application should run on any modern version of Python. If your application requires a specific Python version, create a runtime.txt file in your repository with the version number. Consult the build with Python page to learn more.

Push the project to GitHub

In the project directory, initialize a new git repository by running the following command:

git init

We will use this repository to version the application code and push the changes to a GitHub repository. If you don't have an existing GitHub repository to push the code to, you can create a new one and run the following commands to commit and push changes to your GitHub repository:

Make sure to replace <YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> with your GitHub username and repository name.

git add requirements.txt
git commit -m "Initial commit"
git push -u origin main

Deploy to Koyeb using git-driven deployment

To deploy the Python FastAPI app on Koyeb, using the control panel (opens in a new tab), on the Overview tab, click Create Web Service and follow the steps below:

  1. Select GitHub as the deployment method.
  2. Choose the GitHub repository and branch containing your application code. Alternatively, you can enter our public FastAPI example repository (opens in a new tab) into the Public GitHub repository at the bottom of the page:
  3. In the Builder section, choose Buildpack and click the override toggle associated with the Run command field. In the field, input:
    uvicorn main:app --host
  4. Name your App, for instance, koyeb-fastapi.
  5. Click the Deploy button.

A Koyeb App and Service will be created. Your application will be built and deployed to Koyeb. Once the build has finished, you will be able to access your application running on Koyeb by clicking the URL ending with

Deploy to Koyeb using a pre-built container

As an alternative to using git-driven deployment, you can deploy a pre-built container from any public or private registry. This can be useful if your application needs specific system dependencies or you need more control over how the build is performed.

To dockerize the Python FastAPI application, create a Dockerfile in your project root directory and copy the content below:

FROM python:3-alpine AS builder
RUN python3 -m venv venv
COPY requirements.txt .
RUN pip install -r requirements.txt
# Stage 2
FROM python:3-alpine AS runner
COPY --from=builder /app/venv venv
CMD [ "uvicorn", "--host", "", "main:app" ]

The Dockerfile above provides the minimum requirements to run the Python FastAPI application. You can easily extend it depending on your needs.

To build and push the Docker image to a registry and deploy it on Koyeb, refer to the page on deploying pre-built container images.