> For the complete documentation index, see [llms.txt](https://petercheng7788.gitbook.io/developer-note/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://petercheng7788.gitbook.io/developer-note/programming-language/python/uv.md).

# Uv

## Introduction

* An extremely fast Python package and project manager, written in Rust.
* A single tool to replace `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv`, and more.

## Install & manage python version

* `uv python install`: Install Python versions.
* `uv python list`: View available Python versions.

```bash
uv python install 3.12
```

## Create New Project & Virtual environment

```bash
uv init <project_name>
uv venv --python 3.12
source .venv/bin/activate
```

uv will create the following files:

```
.
├── .python-version
├── README.md
├── main.py
└── pyproject.toml
```

#### [`pyproject.toml`](https://docs.astral.sh/uv/guides/projects/#pyprojecttoml) <a href="#pyprojecttoml" id="pyprojecttoml"></a>

* The `pyproject.toml` contains metadata about your project:
* It is similar with `package.json`

```toml
[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = []
```

[`uv.lock`](https://docs.astral.sh/uv/guides/projects/#uvlock)

* `uv.lock` is a cross-platform lockfile that contains exact information about your project's dependencies. Unlike the `pyproject.toml` which is used to specify the broad requirements of your project, the lockfile contains the exact resolved versions that are installed in the project environment. This file should be checked into version control, allowing for consistent and reproducible installations across machines.
* Similar with `package-lock.json`<br>

[`.python-version`](https://docs.astral.sh/uv/guides/projects/#python-version)

The `.python-version` file contains the project's default Python version. This file tells uv which Python version to use when creating the project's virtual environment.

## Managing Dependencies

* There are many ways to install package, after adding package, `pyproject.toml` and `uv.lock` will be updated
* uv is compatible to pip

```bash
uv add <package>
# install exact version
uv add <package==0.20>
# install based on pip files
uv add -r requirements.txt
# install from pip
uv pip install <package>
uv pip list
# ensure all the package are installed based on uv.lock file
uv sync
```

## Tool

* Tools are Python packages that provide command-line interfaces.
* Similar with  `npm install <package> -g`

```bash
uv tool install ruff==0.5.0
ruff --version
// similar with npx 
uvx ruff --version
```

## Docker file

<pre class="language-docker"><code class="lang-docker"><strong># Use a Python image with uv pre-installed
</strong>FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim

# Install the project into `/app`
WORKDIR /app

# Enable bytecode compilation
ENV UV_COMPILE_BYTECODE=1

# Copy from the cache instead of linking since it's a mounted volume
ENV UV_LINK_MODE=copy

# Install the project's dependencies using the lockfile and settings
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --frozen --no-install-project --no-dev

# Then, add the rest of the project source code and install it
# Installing separately from its dependencies allows optimal layer caching
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev

ENV PATH="/app/.venv/bin:$PATH"


EXPOSE 80
ENV PORT 80

ENV LLM_MODEL openrouter/openai/gpt-4o-mini
ENV OPENROUTER_API_KEY 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
ENV GOOGLE_API_KEY AIzaSyBUguvUNCxqha21BhH6r3bOcF48ckoxTz8
ENV CHROMA_HOST 34.44.52.123
ENV CHROMA_PORT 8000

# ENTRYPOINT ["tail", "-f", "/dev/null"]
CMD ["fastapi", "run", "main.py", "--port", "80"]
</code></pre>

{% embed url="<https://github.com/astral-sh/uv-docker-example/blob/main/Dockerfile>" %}

{% embed url="<https://docs.astral.sh/uv/guides/integration/docker/#installing-uv>" %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://petercheng7788.gitbook.io/developer-note/programming-language/python/uv.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.