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.14 with 3rd-party packages dockeree and aituil ) using the following command.
```
uv run --python 3.14 --with dockeree --with aiutil python
```

Similar to the above but start an Ipython shell instead.

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

Initialize a uv managed Python script.
```
uv init --python 3.14 --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_managed_script.py
```
or
```
# preferred
uv run --script /path/to/uv_managed_script.py
```
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.
You might want to pass Python interpretor options (e.g., the -P option) while running a script using uv. This can be done using the command below.
```
uv run python -P /path/to/uv_managed_script.py
```
However, it has one drawback. It doesn't automatically resolve and install dependencies specified in the script. Luckily, with PR merged, this is possible through the option --with-requirements script_with_deps.py which includes inline dependency metadata from script_with_deps.py. So, you can use the following command (though it's verbose).
```
uv run python -P /path/to/uv_managed_script.py --with-requirements uv_managed_script.py
```

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
```