UV 环境管理指南 / 如何将旧项目接入 UV

UV

安装 install

bash 复制代码

curl -LsSf https://astral.sh/uv/install.sh | sh # Linux

check一下安装成功没有

bash 复制代码

uv --version

安装不同版本python

安装python

bash 复制代码

uv python install  # 安装最新版本的python

安装指定版本python

bash 复制代码

uv python install 3.12

安装多个版本的python

bash 复制代码

uv python install 3.12 3.14t 3.8

创建虚拟环境

创建全局虚拟环境

先准备一个专门用于存放环境的目录
bash 复制代码
```
 mkdir -p ~/.venvs
```

创建指定python版本的环境

bash 复制代码

uv venv ~/.venvs/virtual_env --python 3.12
uv venv ~/.venvs/virtual_env -p 3.12

激活环境
bash 复制代码
```
source ~/.venvs/virtual_env/bin/activate
```
注意这时候你的终端提示符会显示你的环境名(virtual_env)
下载包
bash 复制代码
```
uv pip install pandas numpy
```
注意这里，所有的pip指令都需要加上uv
运行代码
bash 复制代码
```
python my_script.py
```
注意这里uv管理的环境python不是python3，可以使用 which python来确定当前使用的python路径
退出环境
bash 复制代码
```
deactivate
```
删除环境
bash 复制代码
```
rm -rf ~/.venvs/virtual_env
```

项目虚拟环境

为新项目创建环境

直接使用uv命令创建项目
bash 复制代码
```
uv init my_project
cd my_project
```
或者手动创建项目目录在初始化环境
bash 复制代码
```
mkdir my_project
cd my_project
uv init
```
uv会在项目根目录下为你创建以下文件和目录
bash 复制代码
```
├── .git
├── .gitignore
├── main.py
├── pyproject.toml
├── .python-version
└── README.md
```
- .git和.gitignore文件不必多说了
- main.py是一个预设的简单脚本，运行一下打印Hello from my_project! (显示的是你的项目名)
- pyproject.toml记录了项目了元数据, 包括项目名称，版本，依赖等信息
- .python-version记录了项目使用的python版本，以及环境路径
- README.md是一个预设的markdown文件，你可以在里面记录项目的简介、安装指南、使用说明以及其他相关文档信息。
- 一般情况下还有一个uv.lock文件，记录了项目的依赖锁定信息, 可读但不建议修改
声明python版本(如果项目需要特定版本的python)
bash 复制代码
```
uv python pin 3.12
```
一般情况下是由于一些包只兼容特定版本的python，才需要声明python版本
添加python依赖包

这里不再是使用uv pip install了，而是直接使用uv add命令来添加依赖包
bash 复制代码
```
uv add pandas numpy
```
如果需要指定版本
bash 复制代码
```
uv add 'pandas==2.0.0' 'numpy>=1.20.0'
```
如果需要添加开发依赖
bash 复制代码
```
uv add --dev pytest ruff
```
运行代码
bash 复制代码
```
uv run script.py
```
这里的uv run命令会自动使用项目环境中的python来运行
移除项目依赖
bash 复制代码
```
uv remove pandas numpy
```
同步/恢复项目环境

当你从 GitHub 克隆了一个别人的（或者你自己的）uv 项目时，本地还没有虚拟环境。此时只需要在项目根目录下运行同步命令：
bash 复制代码
```
uv sync
```

为已有项目创建环境/迁移项目

针对已经存在的项目代码，uv 提供了非常便捷的接入和迁移方式，主要分为以下几种情况：

迁移传统的 requirements.txt 项目

如果你的旧项目使用的是 requirements.txt，你可以轻松将其迁移到 uv 的 pyproject.toml 标准中：
bash 复制代码
```
# 1. 在项目根目录初始化 uv (这不会覆盖你原有的代码文件)
uv init

# 2. 从 requirements.txt 批量导入并添加依赖
uv add -r requirements.txt
```
执行后，uv 会自动解析 requirements.txt 中的包，将它们写入 pyproject.toml 并生成 uv.lock，同时为你创建好虚拟环境。迁移完成后，原来的 requirements.txt 就可以功成身退了。
在没有任何环境管理的已有代码目录初始化

如果你的目录里只有一堆 .py 脚本，还没有任何包管理机制：
bash 复制代码
```
# 直接在当前目录初始化
uv init
```
此时 uv 会生成配置文件。随后，你可以根据代码中 import 的包，逐个使用 uv add <package_name> 将它们添加到项目依赖中。
恢复已有的 uv / 现代化项目环境

如果你从 GitHub 上克隆了一个别人已经配置好 uv 的项目（或者你自己换了台电脑），项目里已经有了 pyproject.toml 和 uv.lock，你完全不需要手动创建环境或一个个安装包，只需要一步：
bash 复制代码
```
uv sync
```
uv 会自动在当前目录下创建 .venv 虚拟环境，并根据锁定的版本极速拉取所有依赖，确保你本地的环境与项目要求的绝对一致。

进阶操作

如果你觉得全局虚拟环境激活和管理太过麻烦，不妨使用shell function来简化操作，换句话说，用一个别名来代替原来需要拖着很长目录的命令

bash 复制代码

# ============== uv ===============

export UV_ENV_DIR="$HOME/Envs" # global envirnment dir

# create a new venv
function uvc() {
   if [ -z "$1" ]; then
      echo "Error: missing environment name. Usage: uvc <env_name>" 
      return 1
   fi
   mkdir -p "$UV_ENV_DIR"
   local env_name="$1"
   shift
   uv venv "$UV_ENV_DIR/$env_name" "$@"
}

# activate a venv
function uva() {
   if [ -z "$1" ]; then
      echo "Error: missing environment name. Usage: uva <env_name>" 
      return 1
   fi
   local env_path="$UV_ENV_DIR/$1/bin/activate"
   if [ -f "$env_path" ]; then
      source "$env_path"
   else
      echo "Error: no such env $1."
   fi
}

# list all venv
function uvl() {
   echo "all of global virtual environment($UV_ENV_DIR):"
   ls -l "$UV_ENV_DIR" 2>/dev/null || echo "No environment found, use uvc to create your first uv environment."

}

# remove a virtual environment
function uvrm() {
   if [ -z "$1" ]; then
      echo "Error: please input env name for remove. Usage: uvrm <env_name>"
      return 1
   fi
   rm -rf "$UV_ENV_DIR/$1"
   echo "already remove $1"
}

_uv_envs_completion() {
        local cur="${COMP_WORDS[COMP_CWORD]}"
        local envs=$(ls -1 "$UV_ENV_DIR" 2>/dev/null)
        COMPREPLY=( $(compgen -W "${envs}" -- "${cur}") )
}

complete -F _uv_envs_completion uva uvrm

本段shell脚本已经过验证, 如有需要, 请将以上内容追加到你的 ~/.bashrc 文件中，并执行 source ~/.bashrc 使其生效。