The program requires Python 3.12, but the version bundled with openEuler differs. How can I run it while keeping the system Python intact? You can use uv to install the required interpreter and create an isolated environment for the program. This method works regardless of whether the program needs a newer or older version than the system Python.
This guide uses Python 3.12 as an example. First check the program’s installation instructions and replace the version number as needed— not all programs should use the latest Python directly. The following steps are performed as a regular user.
We’ll first walk through the full installation and execution process, then address pip usage, slow downloads, and mirror configuration. If the program already provides a Conda environment file, consult the end of this guide for tool selection recommendations.
1. Verify Environment and Install uv
Check whether Python and uv are already available:
python3 --version
uv --version
If uv runs successfully, skip installation. If the command is not found, and you’ve previously installed it, first restart the terminal as instructed during installation to verify PATH—avoid reinstalling.
If not installed, use the official uv installation command. If curl is missing, install it first with sudo dnf install curl. uv is installed per user and does not require sudo:
curl -LsSf https://astral.sh/uv/install.sh | sh
After installation, follow the prompt to restart the terminal, or run in the current Bash session:
source "$HOME/.local/bin/env"
uv --version
If installation or subsequent Python downloads are slow, refer to the section “Slow or Failed Downloads: Where Should You Change?” below.
2. Install Required Python Version
uv python install 3.12
uv will download the corresponding platform-specific Python. Writing 3.12 selects the latest patch version supported by uv for that series. If the program specifies a precise patch version, enter it explicitly. Other series (e.g., 3.10) can be installed similarly by changing the version number.
This step does not overwrite openEuler’s /usr/bin/python3 or require setting the new Python as the global default. System tools continue using the distro-provided interpreter, while the application uses its own interpreter in the next step.
3. Create Environment and Run the Program
Navigate to the downloaded program directory. Assuming it lists dependencies in requirements.txt and uses main.py as the entry point, replace the path and entry file with actual values. Adjust dependencies and startup commands according to the program’s documentation.
By default, uv venv creates a .venv directory in the current folder. If an environment already exists, confirm its purpose to avoid recreating one in use.
cd /path/to/your-program
uv venv --python 3.12
source .venv/bin/activate
python --version
uv pip install -r requirements.txt
python main.py
After activation, python in the current shell points to the .venv environment, and installed packages are isolated within it. Confirm this with:
python -c 'import sys; print(sys.executable)'
The output should point to your-program/.venv/bin/python. Exit the environment after running the program:
deactivate
Next time, enter the program directory and run source .venv/bin/activate again—no need to reinstall dependencies. Different programs can use separate .venv directories, so their dependencies won’t interfere with each other.
uv pip can directly install packages into the virtual environment—there’s no need to install pip first. Never use sudo pip install, nor attempt to modify the /usr/bin/python3 link: dnf and other system tools depend on the system Python and its RPM packages. Keep both environments separate.
Common Requirements and Issues
What if the program documentation requires pip?
uv pip is uv’s built-in package installer—uv does not invoke the external pip command. By default, uv venv does not install pip, so python -m pip may report No module named pip in a fresh environment.
If you wish to use pip as documented, activate the environment and install pip manually:
source .venv/bin/activate
uv pip install pip
python -m pip --version
python -m pip install -r requirements.txt
The version output path should be within the current .venv. Afterward, you can use pip install—but it’s recommended to use python -m pip to explicitly use the pip version associated with the current interpreter, preventing conflicts with other environments’ pip in $PATH. You do not need to install the system’s python3-pip RPM.
If you haven’t created the environment yet and want pip included from the start, use:
uv venv --python 3.12 --seed
See the uv venv documentation for details on --seed. You can also install pip into an existing environment—no need to recreate it for this option.
Slow or Failed Downloads: Where to Change?
First, identify which step is stuck. “Changing the Python mirror” actually refers to three distinct scenarios:
- Installation stuck: The installer is downloading the
uvscript or binary. You can use an existing proxy. If the binary download is slow, you can also set a custom download address. uv python installstuck: The Python interpreter is being downloaded. Use a proxy or set a Python mirror.uv pip install/python -m pip installstuck: Third-party dependencies are being downloaded. Configure PyPI mirrors or use a proxy.
uv’s Python interpreters come from Astral’s python-build-standalone. The installer and interpreter downloads may access Astral’s distribution sites or GitHub; PyPI hosts third-party packages. Changing only the PyPI mirror won’t affect the first two download steps.
Using an Existing Proxy
If your machine already uses an HTTP proxy (e.g., 127.0.0.1:7890), configure it in the current shell:
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"
Replace the address and port with your actual proxy. The variable name https_proxy can still use http:// for the proxy entry. After setting this, re-run your earlier installation or download commands. Both curl, uv, and pip respect these proxy variables. See the uv environment variables and pip proxy guide.
Using export ensures the proxy settings are inherited by both sides of curl ... | sh, including downloads initiated by the script. Setting the variable only on the left side does not pass it to the right side’s sh.
Browser proxy access doesn’t imply terminal proxy setup. When using SSH on a server, 127.0.0.1 refers to the server itself—the proxy address must be reachable from that server.
These settings only affect the current terminal and its subprocesses. To unset them later:
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
No General Proxy? Can You Use GitHub Acceleration Services?
Yes, you can use a URL-prefix-based acceleration service for GitHub downloads. The example below uses gh-proxy.com formatting—other services may use different patterns.
For one-time Python downloads, specify a mirror:
UV_PYTHON_INSTALL_MIRROR='https://gh-proxy.com/https://github.com/astral-sh/python-build-standalone/releases/download' \
uv python install 3.12
uv automatically appends the build date and filename. You don’t need to select the correct architecture archive manually. This setting only affects Python interpreter downloads and does not change PyPI or the uv installer. See Python mirror configuration.
For slow downloads during the uv installer phase, use:
curl -LsSf https://astral.sh/uv/install.sh | \
UV_INSTALLER_GITHUB_BASE_URL='https://gh-proxy.com/https://github.com' sh
The installer still fetches from Astral, but this variable modifies the URL used by the sh script to download the uv binary. It doesn’t fix issues where the installer script itself fails to download. See installer URL configuration.
These acceleration URLs are not proxy servers. They cannot be used in HTTPS_PROXY. They forward requests to third-party services—choose trusted ones; availability may vary over time. The above settings only apply to the specific command they’re used in.
Slow Dependency Installation: How to Set a PyPI Mirror
Using the Tsinghua PyPI Mirror as an example, in an activated virtual environment, choose one of the following based on your tool:
# Using uv
uv pip install -r requirements.txt --default-index https://pypi.tuna.tsinghua.edu.cn/simple
# Using pip installed in the virtual environment
python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
You can also add --default-index to the uv pip install pip command when installing pip later. Both commands replace the default package index for the current operation—no need to run both.
If you use this often, save the config in the project. uv uses uv.toml in the project directory:
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
After this, run uv pip install from the project directory without repeating the URL. If the project already has uv config, update it rather than overwriting. For projects using pyproject.toml, see the uv configuration guide for the correct format.
For pip, run after activating .venv:
python -m pip config --site set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
This writes to .venv/pip.conf. The --site flag determines the scope. The global key doesn’t mean system-wide; it refers to site-local configuration. After saving, retry the original installation command. See the pip configuration guide.
Same URL, different configuration. pip and python -m pip use the same environment’s pip config if they target the same virtual environment. uv pip does not read pip.conf or PIP_INDEX_URL, and pip does not read uv.toml. Environment variables are also independent: uv uses UV_DEFAULT_INDEX, while pip uses PIP_INDEX_URL. See uv vs. pip configuration differences.
If a package or version is unavailable after changing mirrors, temporarily revert to https://pypi.org/simple for that command to distinguish between mirror sync delays and program compatibility issues.
Choosing uv vs. Conda
If you only need a specific Python version and are following the program’s pip/requirements.txt instructions, uv is the straightforward choice.
conda manages not only Python but also native libraries and dependencies in other languages. If the program provides environment.yml, or if the project is organized around a Conda-based scientific computing environment, it’s usually better to stick with Conda. Do not directly treat a Conda environment file as a requirements.txt file. Neither uv nor conda offers operating system-level isolation like containers. See Conda environments documentation.
System packages remain managed by dnf. uv-managed interpreters and virtual environment packages won’t be updated by dnf update. For ongoing maintenance, refer to the uv Python version management documentation and the program’s upgrade instructions.
Verification Note (2026-09-20): The main installation and execution flow have been validated on openEuler 22.03 LTS SP4 and 24.03 LTS SP3 (x86_64 and aarch64). pip, mirror, and proxy usage were re-verified on openEuler 24.03 LTS SP3 (x86_64).