UV Cheatsheet¶

UV can serve as a faster and more efficient package manager for python. It's very easy to switch to uv if you used to use conda and pip. Here are the basic usage of uv.

Overview¶

UV Cheatsheet

How to install UV¶

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

How to manage the virtual environment via UV¶

It's extremely easy to switch to uv if you used to use conda and pip. But uv is much more faster than conda. Here is a way similar to conda and pip to manage the python version and the dependencies via uv.

To create a virtual environment:
```
uv venv
```
To create a virtual environment at my-name(specific path):
```
uv venv my-name
```
To create a virtual environment with specific python version:
```
uv venv --python 3.11
```
To activate the environment:
```
source .venv/bin/activate
```
To deactivate the environment:
```
deactivate
```

The dependencies management in virtual environment is very similar to pip.

To install a package:
```
uv pip install <package>
```
To uninstall a package:
```
uv pip uninstall <package>
```
To list installed packages:
```
uv pip list
```

\(\star\) How to manage the project via UV¶

What is more convienient and elegant is that uv can manage the project along with its environment as well as corresponding dependencies. There is another way to manage the project and dependencies.

In each project, uv will create pyproject.toml file to manage the dependencies and update the environment according to the pyproject.toml file. Here is the way to manage the project and dependencies.

To create a new project,cd to the project directory and run:
```
uv init
```
uv will create a pyproject.toml file.
To create virtual environment according to the pyproject.toml file:
```
uv venv
```
To update the environment according to the pyproject.toml file:
```
uv sync
```
To run the program in the corresponding environment:
```
uv run <command>
```
uv run can directly run the program in the corresponding environment. It's similar to source .venv/bin/activate and python <command>.

Before running the program, uv will also automatically update the environment according to the pyproject.toml file. So uv run is the most convenient way to run any program in this project.
- For example, if you want to run the program main.py, you can run:
```
uv run main.py
```
- if you want to run the shell script script.sh, you can run:
```
uv run zsh script.sh
```
To add the dependencies in the pyproject.toml file:
```
uv add <package>
```
To remove the dependencies in the pyproject.toml file:
```
uv remove <package>
```
To upgrade the dependencies in the pyproject.toml file:
```
uv lock --upgrade-package <package>
```

How to manage the python version via UV¶

To change the python version pinned in a project: run the following command:
```
uv pin python 3.11
```
or directly edit the .python-version file.

How to manage the cache of UV¶

To clean the cache of UV: run the following command:
```
uv cache clean
```

How to insert multiple lines of command in `uv run`¶

Python Example:
```
uv run python - << 'PY'
import math

def f(x):
    return math.sin(x) ** 2

print(f(1.0))
PY
```
Except PY, EOF、END、SCRIPT and xyz can also be used to mark the end of the multi-line command.

Shell Example:

uv run zsh - << 'SCRIPT'
export WORKER_NUM=1024
echo "Worker num is set to ${WORKER_NUM}"
SCRIPT

uv run zsh -lc '
export WORKER_NUM=1024
echo "Worker num is set to ${WORKER_NUM}"
'

Using bash replaces zsh also works.