Setting Up uv on UCloud¶
uv is a high-performance Python package and project manager that streamlines Python version management, package installations, and virtual environment creation. On UCloud, uv comes pre-installed in most applications, including Terminal, Coder, JupyterLab, AlmaLinux Xfce, Ubuntu Xfce.
See the official documentation for detailed features information and uv commands list.
Installing uv¶
The uv package manager can be installed on UCloud by launching any interactive application and executing one of the following shell commands:
$ curl -LsSf https://astral.sh/uv/install.sh | sh
or
$ wget -qO- https://astral.sh/uv/install.sh | sh
To install a specific version, the version number can be appended to the URL. For example:
$ curl -LsSf https://astral.sh/uv/0.5.9/install.sh | sh
When available, uv can also be installed using pip:
$ pip install uv
The full list of available uv commands, including run and pip, can be displayed with:
$ uv help
Note
If uv is not pre-installed, its setup can be automated using an initialization script. This script may be added through the app's Initialization parameter.
Installing and Managing Python¶
By default, uv utilizes existing Python installations. However, it also provides functionality for installing and managing Python versions. Multiple versions can be installed simultaneously using the following command:
$ uv python install 3.10 3.11 3.12
To list all installed versions, the following command can be used:
$ uv python list
A specific Python version can be selected using the -p option, for example, when executing a Python script:
$ uv run -p python3.12.3 program.py
Further details on managing Python versions with uv can be found in the official documentation.
Creating an Environment¶
A virtual environment can be created using the following command:
$ uv venv
By default, the environment is created in /work/.venv.
A custom environment name can be specified:
$ uv venv my-name
Additionally, a specific Python version can be selected during environment creation:
$ uv venv my-name --python 3.11
Using the Environment¶
To activate a uv environment, use the following command:
$ source my-name/bin/activate
Once activated, packages can be managed within the environment using uv pip. For example, to install packages:
$ uv pip install <package-name> <package-name> <package-name>
To list installed packages:
$ uv pip list
To install multiple packages from a file, such as requirements.txt:
$ uv pip install -r requirements.txt
More info on the requirements.txt file can be found in the official documentation.
To deactivate the environment, use:
$ deactivate
Note
To prevent the warning message:
warning: Failed to hardlink files; falling back to full copy...
during package installation, the cache directory should be redirected to a folder within /work using the following command:
$ export UV_CACHE_DIR=/work/uv-cachefolder-name/
Python Environment Detection¶
When modifying an environment using uv pip install or uv pip sync, uv searches for a virtual environment in the following order:
An activated virtual environment, based on the
VIRTUAL_ENVenvironment variable.An activated Conda environment, based on the
CONDA_PREFIXenvironment variable.A virtual environment at
.venvin the current directory or in the nearest parent directory.
Installing Packages in a custom environment¶
If a uv environment exists outside of .venv, packages can be installed by first activating the environment or by setting the VIRTUAL_ENV variable to its path.
Example:
$ VIRTUAL_ENV=/path/to/my-env
$ export VIRTUAL_ENV
uv will use /path/to/my-env for future package installations.
Installing packages in a Conda environment¶
For a pre-existing Conda environment, packages can be installed with uv by activating the environment first, or by setting the CONDA_PREFIX variable:
$ CONDA_PREFIX=/path/to/mycondaenv/
$ export CONDA_PREFIX
A Python interpreter must be associated with the Conda environment for this to work.
Running a Python Script¶
Dependencies can be specified when running a Python script using the --with option. This allows for the inclusion of specific packages at runtime, such as requesting a different version of a package.
For example, the following command includes dependencies when executing a script:
$ uv run --with <package-name> --with <package-name> script.py
Alternatively, dependencies can be defined directly at the top of the Python script. They will be automatically installed at runtime:
# /// script
# dependencies = [
# "requests<3",
# "rich",
# ]
# ///
import requests
from rich.pretty import pprint
resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])
The script can then be executed using:
$ uv run script.py
Further details on running scripts with uv can be found in the official documentation.
Contents