Set default domestic source for uv

doggie · October 31, 2025, 10:30am

This article is transcoded by 简悦 SimpRead, original at zhuanlan.zhihu.com

Hello everyone, I am Xiao Ming.

Brothers, has your Moments timeline recently been flooded by a new tool called uv?

Claiming to be 10 to 100 times faster than pip and venv, written in Rust, and created by Charlie Marsh, the guru behind ruff. Wow, with such a background and speed, it’s basically the “Flash” of Python package management!

So, excitedly, you installed uv and typed uv pip install pandas, ready to experience flight-like speed.

But…

Watching that slowly scrolling download progress bar, are you thinking the same big question as me:

“Where’s the promised speed? How is this any different from my little electric scooter? Did I install a fake uv?”

Hold on! Don’t rush to uninstall!

The problem isn’t uv, but the “distance” between you and the PyPI server.

Where’s the speed bottleneck?

uv is fast mainly in parsing dependencies and local processing. But when it comes to downloading packages, it has to honestly traverse the network.

By default, uv downloads packages from the official PyPI repository (pypi.org), just like pip. This server is located overseas. Accessing it from within China is like taking a winding, possibly often congested country road. No matter how fast your internet is, physical distance and the “jitter” of international networks take their toll.

At this point, uv is like a high-performance supercar stuck at the village entrance, unable to unleash its power.

What to do? Very simple: Change to a highway! This highway is a domestic mirror source.

Tsinghua mirror, Ali mirror, Douban mirror… these mirror sites synchronize the official PyPI repository packages onto domestic servers. Downloading directly from these servers is super fast!

No more chit-chat, let’s do it!

There are three common ways to configure a mirror address for uv. There’s always one that suits you.

Method 1: Last-minute solution (specify in command line)

If you only want to use the mirror occasionally or quickly test the effect, you can directly add a parameter in the command line.

uv pip install numpy --default-index https://pypi.tuna.tsinghua.edu.cn/simple

--default-index is used to specify the mirror address. This way, this time the install command will download from the Tsinghua mirror.

Pros: Simple and direct, use once and done.
Cons: Too troublesome! You have to type a long string every time; hard to remember!

Method 2: Once and for all (set environment variable)

This is the “killer” method we recommend today! By setting an environment variable, every time you use uv later, it will default to downloading from the mirror source.

This magical environment variable is: UV_DEFAULT_INDEX

For macOS / Linux users (zsh/bash):

Open your terminal.
Run the following command to add it into your shell configuration file (like .zshrc or .bashrc).

# Recommended to use Tsinghua mirror
echo 'export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"' >> ~/.bashrc

# Or use Ali mirror
# echo 'export UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple/"' >> ~/.bashrc

# Apply the changes immediately
source ~/.bashrc

Done! From now on, no matter which project you use uv in, it will automatically use the mirror.

For Windows users:

Execute in PowerShell (effective for the current window only):

$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"

Want it permanent? You need to add it to system environment variables.

Right-click “This PC” → “Properties” → “Advanced system settings” → “Environment Variables”.
Click “New” under “User variables” or “System variables”.
Variable name: UV_DEFAULT_INDEX, variable value: https://pypi.tuna.tsinghua.edu.cn/simple
Confirm all dialogs, then restart your terminal (PowerShell or CMD) to apply.

Method 3: Project-level customization (`pyproject.toml`)

If your project needs to keep the mirror source consistent with teammates or has special package source requirements, you can write the config in the pyproject.toml file at the project root.

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

uv will prioritize reading this project-level config, very suitable for team collaboration.

How to know if I configured it successfully?

Simple, just install a package with the -v (verbose) parameter and check the log.

uv pip install -v requests

If you see the mirror address you configured (like pypi.tuna.tsinghua.edu.cn) in the output log instead of pypi.org, then you’ve succeeded!

Now try uv pip install torch with a large package, and feel what it means to “ride a rocket”! Previously, you might have had time to make a cup of coffee waiting; now it might finish as soon as you stand up.

Summary

uv itself is already fast, but paired with domestic mirrors, it’s its full potential!

Temporary use: --default-index parameter.
Personal use: UV_DEFAULT_INDEX environment variable, strongly recommended!
Team use: pyproject.toml file.

A small configuration can launch your Python development experience and efficiency into the stratosphere. Stop suffering slow downloads — start configuring now, immediately!

If you find this article useful, don’t forget to like, bookmark, and share it with your friends still painfully waiting for pip install!

http://weixin.qq.com/r/mp/70R7YwjEElVtrUwA9xH9 (QR code auto recognizer)

Previous recommendations