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

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

Usage¶

Run Executable Scripts of Python Packages¶

Run python -m http.server to start a simple http server.
```
 uvx python -m http.server
```
Run the ruff tool.
```
 uvx ruff -h
```
Run snb from the aiutil package.
```
 uvx --from aiutil snb -h
```

Ad-hoc Python Shell & Scripts¶

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

Manage Projects¶

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

Manage Python Projects Using uv

Installation¶

Usage¶

Run Executable Scripts of Python Packages¶

Ad-hoc Python Shell & Scripts¶

Manage Projects¶

References¶