mirror of
https://github.com/astral-sh/uv.git
synced 2025-08-30 23:37:24 +00:00
144 lines
3.7 KiB
Markdown
144 lines
3.7 KiB
Markdown
# Using uv with FastAPI
|
|
|
|
[FastAPI](https://github.com/fastapi/fastapi) is a modern, high-performance Python web framework.
|
|
You can use uv to manage your FastAPI project, including installing dependencies, managing
|
|
environments, running FastAPI applications, and more.
|
|
|
|
!!! note
|
|
|
|
You can view the source code for this guide in the [uv-fastapi-example](https://github.com/astral-sh/uv-fastapi-example) repository.
|
|
|
|
As an example, consider the sample application defined in the
|
|
[FastAPI documentation](https://fastapi.tiangolo.com/tutorial/bigger-applications/), structured as
|
|
follows:
|
|
|
|
```plaintext
|
|
.
|
|
├── app
|
|
│ ├── __init__.py
|
|
│ ├── main.py
|
|
│ ├── dependencies.py
|
|
│ └── routers
|
|
│ │ ├── __init__.py
|
|
│ │ ├── items.py
|
|
│ │ └── users.py
|
|
│ └── internal
|
|
│ ├── __init__.py
|
|
│ └── admin.py
|
|
```
|
|
|
|
To migrate this project to uv, add a `pyproject.toml` file to the root directory of the project with
|
|
`uv init`:
|
|
|
|
```console
|
|
$ uv init
|
|
$ uv add fastapi --extra standard
|
|
```
|
|
|
|
!!! tip
|
|
|
|
If you have an existing `pyproject.toml`, `uv init` cannot be used — but you may not need to
|
|
make any changes to the file.
|
|
|
|
You should now have the following structure:
|
|
|
|
```plaintext
|
|
.
|
|
├── pyproject.toml
|
|
├── app
|
|
│ ├── __init__.py
|
|
│ ├── main.py
|
|
│ ├── dependencies.py
|
|
│ └── routers
|
|
│ │ ├── __init__.py
|
|
│ │ ├── items.py
|
|
│ │ └── users.py
|
|
│ └── internal
|
|
│ ├── __init__.py
|
|
│ └── admin.py
|
|
```
|
|
|
|
And the contents of the `pyproject.toml` file should look something like this:
|
|
|
|
```toml title="pyproject.toml"
|
|
[project]
|
|
name = "uv-fastapi-example"
|
|
version = "0.1.0"
|
|
description = "FastAPI project"
|
|
readme = "README.md"
|
|
requires-python = ">=3.12"
|
|
dependencies = [
|
|
"fastapi[standard]",
|
|
]
|
|
```
|
|
|
|
From there, you can run the FastAPI application with:
|
|
|
|
```console
|
|
$ uv run fastapi dev
|
|
```
|
|
|
|
`uv run` will automatically resolve and lock the project dependencies (i.e., create a `uv.lock`
|
|
alongside the `pyproject.toml`), create a virtual environment, and run the command in that
|
|
environment.
|
|
|
|
## Initializing a FastAPI project
|
|
|
|
We could reach a similar result to the above by creating a project from scratch with `uv init` and
|
|
installing FastAPI with `uv add fastapi`, as in:
|
|
|
|
```console
|
|
$ uv init app
|
|
$ cd app
|
|
$ uv add fastapi --extra standard
|
|
```
|
|
|
|
By default, uv uses a `src` layout for newly-created projects, so the `app` directory will be nested
|
|
within a `src` directory. If you copied over the source code from the FastAPI tutorial, the project
|
|
structure would look like this:
|
|
|
|
```plaintext
|
|
.
|
|
├── pyproject.toml
|
|
└── src
|
|
└── app
|
|
├── __init__.py
|
|
├── main.py
|
|
├── dependencies.py
|
|
└── routers
|
|
│ ├── __init__.py
|
|
│ ├── items.py
|
|
│ └── users.py
|
|
└── internal
|
|
├── __init__.py
|
|
└── admin.py
|
|
```
|
|
|
|
In this case, you would run the FastAPI application with:
|
|
|
|
```console
|
|
$ uv run fastapi dev src/app/main.py
|
|
```
|
|
|
|
## Deployment
|
|
|
|
To deploy the FastAPI application with Docker, you can use the following `Dockerfile`:
|
|
|
|
```dockerfile title="Dockerfile"
|
|
FROM python:3.12-slim
|
|
|
|
# Install uv.
|
|
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
|
|
|
|
# Copy the application into the container.
|
|
COPY . /app
|
|
|
|
# Install the application dependencies.
|
|
WORKDIR /app
|
|
RUN uv sync --frozen --no-cache
|
|
|
|
# Run the application.
|
|
CMD ["/app/.venv/bin/fastapi", "run", "app/main.py", "--port", "80", "--host", "0.0.0.0"]
|
|
```
|
|
|
|
For more on using uv with Docker, see the [Docker guide](./docker.md).
|