To deploy a FastAPI app on Heroku, you need three files: a Procfile that tells Heroku to run Uvicorn, a runtime.txt with your Python version, and a requirements.txt with fastapi, uvicorn, and gunicorn listed. Once those are in place, you create a Heroku app using the CLI and push your code via Git.
That is the short version. The rest of this guide walks through the full setup including database connection, the errors that trip most developers up, what Heroku actually costs for a FastAPI project in 2026, and a faster path if you want to skip the configuration entirely.
What You Need Before You Start
Before deploying, make sure you have the following in place:
- A FastAPI app that runs locally without errors
- A requirements.txt file that includes fastapi, uvicorn, and gunicorn
- A Heroku account. The cheapest option is the Eco plan at $5 per month, but Eco dynos sleep after 30 minutes of inactivity. For an API that needs to respond instantly, the Basic plan at $7 per month is the practical minimum
- The Heroku CLI installed and logged in on your machine
- Git initialized in your project directory with your code committed
If your app has a database, you will also need to know which database type you are using. Heroku supports PostgreSQL natively. MySQL requires a third-party addon.
**_
Not sure what Heroku pricing actually looks like for a FastAPI project in 2026? The numbers might surprise you.
_**
How to Deploy a FastAPI App on Heroku
Step 1: Prepare the Required Files
Heroku does not know how to start your FastAPI app unless you tell it. Three files handle that.
The first is the Procfile. This is a plain text file you create in the root of your project with no file extension. It contains a single line that tells Heroku to use Uvicorn as the server and to bind to the port Heroku assigns dynamically. The key thing most guides get wrong here is hardcoding a port number like 8000. Heroku assigns its own port at runtime and injects it as an environment variable. Your Procfile must use that variable or your app will crash immediately after deployment.
The second is runtime.txt. This tells Heroku which Python version to use. Python 3.11 and 3.12 are both supported in 2026. If you skip this file, Heroku will pick a version that may not match your local environment.
The third is requirements.txt. This must list every package your app depends on, including fastapi, uvicorn, and gunicorn. Gunicorn is required because Heroku uses it as the process manager. If it is missing from requirements.txt, your build will fail.
Step 2: Create Your Heroku App and Deploy
Once your files are ready, open your terminal and log in to the Heroku CLI. Running heroku create generates a new app with a random name and sets up a Git remote called heroku pointing at it. If you want a custom name, you can pass it as an argument to that command.
Before pushing your code, set any environment variables your app needs. Things like API keys, secret keys, and database URLs should never be hardcoded in your source files. The Heroku CLI lets you set these with a simple command, and they are injected into your app at runtime where you can access them through Python’s os.environ or through Pydantic Settings if you are using that pattern.
Once your environment variables are set, push your code to Heroku using Git. Heroku will detect your Python app, install dependencies from requirements.txt, run the Procfile command, and start your app. The whole process takes about a minute. When it finishes, you can open your live app URL directly from the terminal or find it in the Heroku dashboard.
Step 3: Connect a Database
If your FastAPI app uses a database, you need to add it as a Heroku addon rather than connecting to an external database separately.
For PostgreSQL, Heroku has a native offering. You add it through the CLI or the dashboard, and Heroku automatically creates a DATABASE_URL environment variable that contains the full connection string. In your FastAPI app, you pass that variable to SQLAlchemy when creating the database engine. No manual host, port, or credentials to configure.
Running Alembic migrations on Heroku works by running your migration command through the Heroku CLI after deployment. You do not run it locally against the Heroku database directly. Heroku lets you execute one-off commands against your live app, so you run the migration the same way you would run any other management command, just through the CLI.
The Essential-0 Postgres plan gives you 1GB of storage and handles most early-stage APIs comfortably. When your data grows or you need connection pooling, you will need to move to a higher tier.
**_
The Heroku Postgres limits are tighter than most developers expect. Here is what you will actually hit in production.
_**
Common FastAPI Heroku Errors
Most FastAPI deployments on Heroku fail for the same handful of reasons. Here is what each one means and how to fix it.
H10: App Crashed
This is the most common error and almost always comes down to the same thing: the Procfile is not using the PORT environment variable that Heroku provides. When Heroku starts your app, it assigns a port dynamically and expects your server to bind to it. If your Procfile has a hardcoded port number instead of referencing the PORT variable, Heroku cannot connect to your app and logs it as a crash. Check your Procfile, make sure it references PORT correctly, and redeploy.
Worker Timeout
Heroku’s default request timeout is 30 seconds. If your FastAPI endpoint takes longer than that to respond, Heroku kills the request and logs a timeout error. This is common with ML inference endpoints or anything that does heavy computation. The fix is either to optimize your endpoint so it responds faster, move long-running tasks to a background worker, or increase the number of gunicorn workers so requests do not queue behind each other.
ModuleNotFoundError
This means a package your app imports is not listed in requirements.txt. It works locally because the package is installed in your local environment, but Heroku builds a fresh environment from requirements.txt and does not have it. Go through your imports, find the missing package, add it to requirements.txt, commit, and push again.
CORS Errors After Deployment
FastAPI apps that work locally often hit CORS errors in production because the allowed origins are set to localhost. When your frontend or API client sends requests from a real domain, Heroku sees them coming from an origin that is not on the allowed list and blocks them. Update your CORS middleware configuration to include your production domain, not just localhost.
Dyno Sleeping on the Eco Plan
Eco dynos sleep after 30 minutes of inactivity. When the next request comes in, the dyno has to wake up first, which adds several seconds of latency to that first request. For a web app this is annoying. For an API that other services depend on, it is a real problem. The only fix is to upgrade to a Basic or Standard dyno, which stays awake. There is no way to disable sleeping on the Eco plan.
**_
There is a reason developers are deploying FastAPI without Heroku in under 5 minutes. No Procfile, no debugging.
_**
Why Kuberns Is a Better Choice for FastAPI in 2026
Every error listed above covers the H10 crash, the worker timeout, the dyno sleeping, and more. You write the Procfile, you configure gunicorn, you choose the right dyno tier, you set up addons manually. For a simple app that is manageable. For a FastAPI project handling real traffic or AI workloads, it becomes a maintenance overhead you did not sign up for.
Kuberns was built to remove that overhead entirely. It uses AI agents to handle the deployment layer so you do not have to.
When you connect your GitHub repo to Kuberns, the AI agent reads your project, detects that it is a FastAPI application, and configures the server automatically. No Procfile. No gunicorn tuning. No PORT variable to get right. It just works.
The agentic AI layer does not stop at the initial deploy. It monitors your app in production, watches resource usage, and scales automatically when traffic increases. If your API gets a spike at 2am, Kuberns handles it. You do not get paged, you do not log in to add dynos manually, and you do not get a bill for a dyno tier you had to upgrade to just in case.
For FastAPI specifically, Kuberns handles the async runtime correctly out of the box. Uvicorn workers are configured based on your actual resource allocation, not a gunicorn default you have to tune. Environment variables are set through a clean dashboard interface. Database connections are managed automatically.
The pricing model is also different. Heroku charges per dyno whether or not your app is using the full capacity of that dyno. Kuberns charges based on actual resource consumption, which means you are not paying for idle capacity.
For AI and ML FastAPI applications in particular, where inference endpoints can be resource-intensive and traffic is unpredictable, having an AI agent manage the infrastructure is a natural fit.
**_
Kuberns vs Heroku covers the full picture of why developers are making the switch.
_**
What Heroku Actually Costs for a FastAPI App in 2026
Heroku removed its free tier in 2022. Every app costs money now, and the real monthly bill for a production FastAPI setup is higher than most guides show.
The Eco plan at $5 per month is the entry point, but it is not suitable for APIs. Eco dynos sleep after 30 minutes of inactivity, which means your API will have cold start delays whenever it has not received traffic recently. If your FastAPI app serves other services or has users who expect instant responses, Eco is not viable.
The Basic plan at $7 per month keeps your dyno awake but gives you a single dyno with no autoscaling. If traffic spikes, requests queue and your API slows down. This works for low-traffic internal tools or personal projects but not for anything with real production load.
Standard dynos start at $25 per month and go up to $50 per month. These support autoscaling, multiple dynos, and are the minimum for production APIs that need to handle variable traffic without manual intervention.
On top of the dyno cost, you need to factor in Heroku Postgres. The Essential-0 plan adds $5 per month. If you need more than 1GB of storage or more than 25 connections, you move to Essential-1 at $9 per month or higher. Add monitoring addons, logging, and any other services your app needs, and a production-ready FastAPI setup on Heroku realistically costs $40 to $80 per month before your app sees significant traffic.
**_
Most developers only find out how much Heroku really costs after the first invoice arrives.
_**
Heroku vs Kuberns for FastAPI: How They Compare
Here is a direct side-by-side look at what each platform gives you when deploying a FastAPI app:
Top comments (0)