How to use FastAPI with uv and src-layout?

[brainbytes42]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched in the documentation/README.
• I already searched in Google "How to do X" and didn't find any information.
• I already read and followed all the tutorial in the docs/README and didn't find an answer.

Commit to Help

• I commit to help with one of those options 👆

Example Code

## File-Structure #############################################
foo
 \- src
     \- foo
         \- __init__.py
         \- main.py
 \- pyproject.toml


## pyproject.toml #############################################
[project]
name = "foo"
version = "0.1.0"
description = "Add your description here"
requires-python = ">=3.14"
dependencies = [
    "fastapi[standard]>=0.123.5",
]

[build-system]
requires = ["uv_build>=0.9.14,<0.10.0"]
build-backend = "uv_build"


## main.py ####################################################
from fastapi import FastAPI

print("Hello from foo!")

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}



## Run script with uv #########################################
> uv run -m foo.main         # prints "Hello from foo!"
> uv run fastapi dev src/foo/main.py       # runs the server, but needs "src"

Description

I generally use uv as package manager and build-tool und src-layout for better testability.
To run a simple module, I'd do uv run -m foo.main as shown above - note that the src-folder is not contained in the command, but uv handles the package-import.

Now I try to use FastAPI-CLI in this setup, but I only get it to run with the full path including "src" - which suggests, the script will be run directly and not as an imported package - so the controlled environment usually provided by uv is ignored.

Is there any clean/canonical way to run fastapi-CLI with uv and src-layout?

Thanks!

Operating System

Windows

Operating System Details

Win 11

Python Version

3.14

Additional Context

No response

[arian-bozorgzad]

Hey! I think the cleanest way to handle this is to configure the FastAPI entrypoint directly in "pyproject.toml".

Since your project already uses "uv_build" and the "src/" layout, you shouldn't need to pass "src/foo/main.py" every time.

Just add:

[tool.fastapi]
entrypoint = "foo.main:app"

Then run this from the project root:

uv run fastapi dev

This tells FastAPI CLI to import "app" from "foo.main" instead of trying to discover it from a file path.

One small thing I'd point out: running "uv run fastapi dev src/foo/main.py" doesn't actually bypass uv's environment. The "src/" part is just the file path FastAPI CLI uses to locate your app.

Since you already have a build system configured, uv should install your project into its environment. You can verify the import with:

uv run python -c "from foo.main import app; print(app)"

If that works, i belive the package import itself is fine.

There's also a CLI option if you don't want to modify "pyproject.toml":

uv run fastapi dev --entrypoint foo.main:app

I'd go with the "pyproject.toml" approach. It's cleaner, and you don't have to repeat the entrypoint every time .

I looked it up and the FastAPI docs actually recommend this approach too:
https://fastapi.tiangolo.com/fastapi-cli/#configure-the-app-entrypoint-in-pyprojecttoml

Hope this helps!! Let me know