Migrate an Existing Project

Already have a FastAPI project? This guide will help you preparing your existing codebase for deployment to FastAPI Cloud.

Prerequisites

• An existing FastAPI application
• A pyproject.toml or requirements.txt file
• A FastAPI Cloud account

1. Verify Your Project Structure

FastAPI Cloud works with standard Python project layouts. Your project should have:

• A pyproject.toml (recommended) or requirements.txt file in the root
• A FastAPI application instance (typically named app)

A typical structure looks like:

myproject/
├── pyproject.toml
├── main.py
└── ...

or:

myproject/
├── pyproject.toml
├── app/
│   └── main.py
└── ...

2. Check Your Dependencies

Using pyproject.toml (Recommended)

Ensure fastapi[standard] is in your dependencies. This includes the FastAPI Cloud CLI needed for deployment.

Using uv

uv add "fastapi[standard]"

Using pip

First, add it to your pyproject.toml:

[project]
dependencies = [
    "fastapi[standard]",
    # ... your other dependencies
]

Then install:

pip install -e .

Using requirements.txt

If you use requirements.txt, add fastapi[standard]:

fastapi[standard]
# ... your other dependencies

Note

If you already have fastapi in your dependencies, replace it with fastapi[standard] to get the CLI tools.

3. Specify Your Python Version

FastAPI Cloud needs to know which Python version to use. Add the requires-python field to your pyproject.toml:

[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.12"

To pin a specific version (useful if you have dependencies that don’t support the latest Python):

requires-python = "==3.12.*"

Alternatively, you can create a .python-version file in your project root:

3.12

4. Configure the Entrypoint

FastAPI Cloud auto-detects your app if it’s in standard locations (main.py, app.py, or app/main.py). If your app is elsewhere, configure it in pyproject.toml:

[tool.fastapi]
entrypoint = "src.myapp.main:app"

This tells FastAPI Cloud to import app from src/myapp/main.py.

Verify Locally

Test that your configuration works by running:

fastapi dev

If this works without passing a file path, your configuration is correct and fastapi deploy will work too.

5. Review Files to Upload

By default, FastAPI Cloud respects your .gitignore file (any files listed there won’t be uploaded). To customize this, create a .fastapicloudignore file in your project root. It uses the same syntax as .gitignore but takes precedence:

# Ignore additional files not in .gitignore
tests/
data/
*.csv

# Un-ignore files that are in .gitignore (useful for build outputs)
!dist/

See Ignore or Un-ignore Files for more details.

6. Set Up Environment Variables

If your app uses environment variables (database URLs, API keys, etc.), you’ll need to configure them in FastAPI Cloud.

You can set your environment variables using the CLI:

fastapi env set DATABASE_URL "postgresql://..."
fastapi env set SECRET_KEY "your-secret-key"

Or set them in the FastAPI Cloud Dashboard under your app’s settings.

See Environment Variables for more details.

7. Deploy

Login and deploy your application:

fastapi login
fastapi deploy

The CLI will upload your code, and then FastAPI Cloud will install dependencies, and deploy your app.

Deploying to FastAPI Cloud...
🚀 Preparing for liftoff! Almost there...
✅ Deployment successful!
🐔 Ready the chicken! Your app is ready at https://myapp.fastapicloud.dev

Migration Checklist

Use this checklist to verify your project is ready to be deployed in FastAPI Cloud:

• fastapi[standard] is in your dependencies
• Python version is specified (requires-python or .python-version)
• fastapi dev runs successfully without passing a file path (or you’ve configured the entrypoint)
• Reviewed .gitignore and optionally created .fastapicloudignore for deployment-specific rules
• Environment variables are configured in FastAPI Cloud

Once all items are checked, run fastapi deploy and your app should be live within minutes. 🪄

Common Migration Scenarios

Using Docker Locally

If you currently use Docker for local development, you can continue to do so. FastAPI Cloud doesn’t require any Docker configurations, it will build and run your app directly. Just ensure your pyproject.toml has the correct dependencies and Python version.

Migrating from Poetry, Pipenv, or pip to uv

If your project uses Poetry, Pipenv, or pip with requirements.txt, you can migrate to uv, which would make your setup faster and simpler, and will have full compatibility with FastAPI Cloud.

You can easily migrate your project to uv with the third-party tool migrate-to-uv:

uvx migrate-to-uv

That will read your configuration files and update them to use uv.

For example, it will update dependencies declared with Poetry’s pyproject.toml format to uv’s format and will generate a new uv.lock file.