[UV](https://docs.astral.sh/uv/) is a fast new [[Python]] [[virtual environment]] and package manager by the developers of [[Rust]]. It is considerably faster than [[mamba]] and offers many of the advanced features of [[Poetry]] like lock files for better environment reproducibility across workstations. Instead of activating an environment as usual, all you need to do is be within the project directory to have the same effect. ## install on WSL To install on [[Windows Subsystem for Linux|WSL]], open your Ubuntu terminal and use command ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` To confirm installation, use ```bash uv -V ``` ## initialize an environment Use `uv` to create a project in your `projects` directory with ```bash uv init <my-project> ``` or initialize `uv` within an existing project with ```bash uv init ``` ## add a dependency To add a dependency use ```bash uv add <package> ``` From a [[requirements.txt]] file use ```bash uv add -r requirements.txt ``` ## remove a dependency To remove a dependency, simply delete from your `pyproject.toml` file or use ```bash uv remove <package> ``` ## list dependencies To list dependencies, use ```bash uv pip list ``` ## run a script Running scripts with `uv` is a little different than in other package managers like conda. You don't need to activate an environment provide you are executing a script from within a project (i.e., a directory with `pyproject.toml` file included). ```bash uv run <script.py> ``` ## with Jupyter Notebook To run notebooks in [[VS Code]], add [[iPython kernel]] to your environment. ```bash uv add ipykernel ``` To use the [[Jupyter Notebook]] browser environment with `uv` simply use ```bash uv run --with jupyter jupyter lab ``` This will install and launch Jupyter Lab with your dependencies accessible for import. You don't even need to install Jupyter beforehand! One of the most unique features of `uv` is its ability to create virtual environments automatically when you run a script from within a project directory. ## optional dependencies Often I install a variety of dependencies when trying out new approaches, dependencies I don't want in my final environment. For this, use [optional dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#optional-dependencies). I like to create a `nb` list of optional dependencies for all of my notebooks. If you need even more fine-grained control (e.g., dependency conflicts between notebooks), use multiple optional lists or even one list per notebook. To add a dependency as optional ```bash uv add <package> --optional <list> ``` where `list` creates or adds to a named list of optional dependencies. I use `nb` for notebook environments. Alternatively, specify them in the `pyproject.toml` file. You might for example move dependencies from the main list to an optional list ```toml [project] name = "my-project" version = "0.1.0" dependencies = [ "pandas" ] [project.optional-dependencies] nb = [ "ipykernel" "matplotlib" ] ``` To build a library with extras, use `sync` with the `extra` flag. ```bash uv sync --extra nb ``` To enable all extras across multiple lists, use the `--all-extras` option. This may seem strange at first, creating new environments depending on the task, but the power of `uv` to quickly install dependencies gives it the power to do this seamlessly. ## dependency groups Dependency groups is a `uv` concept that allows you to install specific packages for specific workflows (think dev, testing, documentation). ```toml [project] name = "my-project" version = "0.1.0" dependencies = [ "pandas" ] [dependency-groups] docs = [ "mkdocs-material~=9.5", ] ``` To build a library with dependency groups, use `sync` with the `group` flag. ```bash uv sync --group dev ``` To enable all extras across multiple lists, use the `--all-extras` option. ## sync Sync is the utility to rebuild environments in `uv`. Sync is typically done automatically, but can be run manually or can be used to install optional or grouped dependencies. ```bash uv sync ```