Install and use uv under network restrictions

uv is an excellent tool for managing Python environments and packages. However, it relies on network connectivity to access its endpoints, such as github.com and pypi.org, to install uv itself, Python interpreters, and packages.

In this post, I will share how to install and use uv in an environment with network restrictions.

Install uv

The original scritp to install uv is:

curl -Ls https://astral.sh/uv/install.sh | sh

This script may break in a network-restricted environment. Instead, we can use a github mirror to download the script and install uv: Given a working github mirror in our network https://gh-proxy.org/, the following command can be used to install uv:

export UV_INSTALLER_GHE_BASE_URL="https://gh-proxy.org/https://github.com"
curl -LsSf https://gh-proxy.org/https://github.com/astral-sh/uv/releases/latest/download/uv-installer.sh | sh

As the uv install script use the UV_INSTALLER_GHE_BASE_URL environment variable to determine the base URL for downloading the installer, we can set it to the github mirror URL to ensure that the script can be downloaded successfully. Find a working github mirror in your network and replace https://gh-proxy.org/ with the mirror URL in the above command to install uv.

Use uv to install Python interpreters

Python interpreters management is one of the core features of uv. However, uv downloads Python interpreters from the its python standalone github repository, which may also be blocked in a network-restricted environment. We may encounter network issue when install it via uv python install 3.12 command. uv allows us to use a python-install-mirror instead of the default https://github.com/astral-sh/python-build-standalone/releases/download to install python interpreters.

Simlar to installing uv, using a proper github mirror works for this issue. Putting it into ~/.config/uv/uv.toml as following gonna fix it.

python-install-mirror = "https://gh-proxy.org/https://github.com/astral-sh/python-build-standalone/releases/download"

Find your self a working github mirror in your network and replace https://gh-proxy.org/ with the mirror URL in the above config to install Python interpreters via uv. If you are confused about where is the config file, check the uv documentation for more details.

Use uv to install packages

uv uses pypi.org as the default package index to install packages. In a network-restricted environment, we can use a pypi mirror to install packages via uv. uv allows us to set a index to specify the package index URL. Putting it into ~/.config/uv/uv.toml as a fix if you want to make it work globally.

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"

Find a working pypi mirror in your network and replace https://pypi.tsinghua.edu.cn/simple with the mirror URL in the above config to install packages via uv.

Setting it to the environment variable UV_INDEX or passing it via --index flag also works, but putting it into the config file is more convenient if you want to make it work globally.

Putting it into the projct-specific uv.toml also works if you only want to use the mirror for a specific project.

Finally, enjoy your python trip with uv!