Manage Python environments with uv
Note
This section introduces using uv to create a completely isolated Python environment. This usually means you need an environment with a different Python version from the one provided by the runtime, or you want to fully isolate dependencies for a project. If you only want to install a few additional packages, you don’t need to create a separate environment — you can simply use pip install --user <package> This installs the packages into your workspace, and they will remain available even after a restart. For more details, see Persisting pip Dependencies.
Newer Ubuntu 24.04 runtimes (such as those used by vllm 0.20 and later, and pytorch 2.11 and later) use uv to manage Python, and no longer include Conda. The default Python environment provided by the runtime is located at /opt/venv.
Caution
Using uv pip install <package> directly will install the package into the built-in /opt/venv, making it immediately available. However, this directory is not persistent, so the installed packages will be lost after the container restarts.
If you need the installation to persist after a restart:
- For installing only a small number of packages, use
pip install --user(Note that uv does not support--user, so you should use the systempip); - If you need a fully isolated environment, follow the instructions below to create one under
/hyperai/home.
Check whether the current runtime is using uv or Conda:
$ uv --version # If a version number is displayed, it indicates that the runtime is using uv, and you should follow this documentation.
$ conda --version # If a version number is displayed, it indicates that the runtime is using Conda, and you should refer to the「Dependency Management with Conda」section.Create a new environment using uv.
1. Create a new environment under /hyperai/home.
cd /hyperai/home
uv venv myenvThis usually takes only a few seconds to complete. Then activate the new environment:
source /hyperai/home/myenv/bin/activateNote
The key to preserving the environment is to create it under /hyperai/home. After the container restarts, you can simply re-run the source command above to continue using the environment.
2. Install dependencies in the environment.
After activating the environment, install dependencies using uv pip install:
uv pip install torch torchvision
uv pip install -r requirements.txtNote
When installing dependencies in a self-created isolated environment, do not use the --user flag. If --user is added, the packages will be installed under /hyperai/home/.pylibs instead of the newly created environment, which may lead to dependency conflicts.
3. Need a different Python version.
uv can download any version of Python, but make sure you explicitly set the download location to the workspace directory first. Otherwise, after the container restarts, the interpreter will be lost and the entire environment will become invalid:
export UV_PYTHON_INSTALL_DIR=/hyperai/home/.uv/python
uv venv myenv --python 3.11Caution
The environment variables set using export only take effect in the current terminal session. When creating environments later (including after a container restart), you must re-run the export commands above first—otherwise, the newly created environment may become invalid after the next restart.
However, already created environments are not affected: the interpreter has been saved in the workspace, and after a restart you can simply run source again to reactivate and continue using the environment.
When creating an environment using the runtime’s built-in Python version (i.e., without specifying --python , or using the same version as the built-in one), there is no need to set this variable.
Integrating the new environment with the Jupyter workspace
Similar to Conda environments, you can install ipykernel in the environment and register it as a Jupyter kernel. This allows you to switch between different environments within the same Jupyter workspace:
source /hyperai/home/myenv/bin/activate
uv pip install ipykernel
python -m ipykernel install --user --name=myenv --display-name="Python (myenv)"After reopening the Jupyter workspace page, you will be able to see the newly added option in the kernel list.
Note
The kernel registration information is stored in a system directory, so it will be lost after the container restarts. After a restart, you only need to re-run the last command (python -m ipykernel install) to restore it. The environment itself is saved in the workspace and will not be lost.