[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. See this guide to [[porting to uv]] if initializing into an existing project using [[pip]] or [[conda]]. ## install on Linux or WSL To install on Linux or [[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. ## dependency groups and conflicts Use [optional dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#optional-dependencies) to limit the dependency tree for published libraries. Use [development dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#development-dependencies) with dependency groups to install local only dependencies that aren't required for the final package (think docs, notebooks, testing, etc). These will be automatically excluded when the package is published. If you have **dependency conflicts** between groups, you must specify conflicts to `uv` explicitly (see [docs](https://docs.astral.sh/uv/concepts/projects/config/#conflicting-dependencies)) as it tries to resolve all dependencies together. In practice I've found it's generally best to just set up another project, as this will create a second `.venv` folder and just isn't well supported (you need to remember to use the `--active` flag with every command). ## 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 ``` To build a library with optional dependencies (i.e., "extras"), use `sync` with the `extra` flag. ```bash uv sync --extra <dependency-group> ``` To enable all extras across multiple lists, use the `--all-extras` option.