Manage Python Projects Using uv

Things on this page are fragmentary and immature notes/thoughts of the author. Please read with your own judgement!

Installation

curl -LsSf https://astral.sh/uv/install.sh | sh

curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/usr/local/bin" sh

You can start an ad-hoc Python shell ( e.g., Python 3.13 with 3rd-party packages dockeree and aituil ) using the following command.
```
uv run --python 3.13 --with dockeree --with aiutil python
```

Similar to the above but start an Ipython shell instead.

uv run --python 3.13 --with dockeree --with aiutil --with IPython python -m IPython

Initialize a uv managed Python script.
```
uv init --python 3.13 --script example.py
```
Notice that if the script example.py already exists, uv will just append metadata lines into it.
You can add dependencies to a uv managed Python scripts using the following command.
```
uv add --script example.py 'requests<3' 'rich'
```
You can run a uv managed Python script using
```
uv run /path/to/uv_init_pyscript
```
or
```
uv run --script /path/to/uv_init_pyscript
```
Those 2 commands will automatically resolve and install dependencies specified in the script. This can be simplified by add the shebang #!/usr/bin/env -S uv run or #!/usr/bin/env -S uv run --script into the Python script, so that you can invoke the script as an executable directly. Notice that there's currently no way to pass the Python interpreter options if you want uv to automatically resolve and install dependencies of a Python script. You can pass Python interpreter options, say -P, using uv run python -P .... However, when used to run a Python script (uv run python -P /path/to/uv_init_pyscript), it won't automatically resolve and install dependencies specified in the script. There are 2 ways to address this issue. First, you can configure the corresponding Python environment variable (e.g., PYTHONSAFEPATH=1) if available. Second, Wait for the PR (which supports --with-requirements script.py to include inline dependency metadata from another script) to be merged and released.

Migrate from other Python projects to uv.
```
uvx migrate-to-uv
```
Initialize a new uv project with the given name.
```
uv init --package new_project_name
```
Initialize the current project as a uv project.
```
uv init --package
```
Update the lock file (changing as little as possible).
```
uv lock
```
Update the lock file ensuring that dependencies are the newest version allowed by the spec.
```
uv lock --upgrade
```
Create a virtual environment if one doesn't already exist and install all dependencies.
```
uv sync
```
Install all dependencies including optional ones.
```
uv sync --all-extras
```
Install all dependencies but not the current project.
```
uv sync --no-install-project
```
Build the project.
```
uv build
```
Publish the project.
```
uv publish
```