====== uv – Python package manager ======
----

This document describes ''uv'' usage on the LUIS cluster. 
For detailed instructions on ''uv'' features, including installation of deep learning stacks, 
please refer to the official ''uv'' [[https://docs.astral.sh/uv|documentation]]. 

''uv'' is a fast Python package manager and environment tool, serving as a modern alternative to ''pip'', ''virtualenv'', and partially ''conda''.
It allows users to create **isolated Python environments** and install packages **efficiently**.

To make ''uv'' available, load the module:

<code>
module load GCCcore/.14.2.0 uv/0.9.22 
</code>

Check:
<code>
uv --version
</code>

To check other available ''uv'' module versions, run:
<code>
module -r spider ^uv
</code>

===== Creating a uv project =====

A **uv project** is a directory containing your Python code along with project metadata that ''uv'' uses to manage dependencies, scripts, and build information.

Creating a project does not automatically create a virtual environment, as it only sets up the project structure.

The simplest way to create a project is to let ''uv'' create the directory and initialize the project:
<code>
uv init ~/my-python-project
</code>
This will create the directory ''~/my-python-project'' and initialize the project inside it.

The ''~/my-python-project'' directory will contain:
<code>
~/my-python-project/
├── .git
├── .gitignore
├── .python-version
├── main.py
├── pyproject.toml
└── README.md
</code>

A ''uv'' project can also be initialized within an existing directory by navigating into it and running ''uv init''

===== Creating a virtual environment =====

To actually install and isolate Python packages, you need a Python runtime environment.
The environment can be located within the project directory or anywhere else on the filesystem.

Create a new Python environment in the directory ''~/myenv'' (i.e. in ''$HOME/myenv''):
<code>
uv venv ~/myenv 
</code>
The directory ''~/myenv'' is created if it does not exist, and must be empty if it already exists.

**Note**: Create virtual environments in your project’s dedicated [[guide:storage_systems#software_-_install_software_for_your_group_here|$SOFTWARE]] directory rather than in [[guide:storage_systems#home_-_configuration_files_and_setups_don_t_do_big_work_in_your_home_though_pun_intended|$HOME]], as home directories have limited space.


Activate the virtual environment:
<code>
source ~/myenv/bin/activate 
</code>

Exit the currently active virtual environment:
<code>
deactivate 
</code>

===== Installing packages =====

Install packages using ''uv pip'':

<code>
uv pip install numpy scipy matplotlib 
</code>

Install from a requirements file:
<code>
uv pip install -r requirements.txt 
</code>

**Note**: On the LUIS cluster, you must first create and activate a virtual environment **before** installing Python packages with ''uv''.

===== Selecting the Python version =====

As ''uv'' does not install or download Python but instead uses the Python interpreter 
currently available in the user environment (by default the one provided by the cluster
operating system), any alternative Python version **must be loaded via Lmod** into 
the environment **before** creating a virtual environment.

List available Python modules:
<code>
module -r spider ^Python 
</code>

The LUIS cluster uses a hierarchical module layout, where Python modules may require other 
modules (e.g. compiler) to be loaded first. 
To determine the required dependencies, query the specific version:
<code>
module spider Python/3.11.6 
</code>

This command shows which parent modules must be loaded.

After loading the required modules, load Python:
<code>
module load Python/3.11.6 
</code>

Note that the required parent modules and the Python module can be loaded in one command; the order matters (parent modules first):
<code>
module load <parent-module> Python/3.11.6
</code>

Verify:
<code>
python --version 
</code>

Then create the environment:
<code>
uv venv ~/myenv 
</code>

===== Freezing environments =====
To save the current state of installed packages in a virtual environment, use:

<code>
source ~/myenv/bin/activate
uv pip freeze > requirements.txt 
</code>

This generates a list of all packages and their versions in //requirements.txt// format, 
which can be used to recreate the environment elsewhere:

<code>
uv venv ~/newenv 
source ~/newenv/bin/activate 
uv pip install -r requirements.txt 
</code>

To see which packages are currently installed in the environment in a tabular format, use:
<code>
uv pip list 
</code>

For a full list of available ''pip'' commands within ''uv'', type:
<code>
uv pip --help
</code>