# onekeysetuv

**Repository Path**: lilhand/onekeysetuv

## Basic Information

- **Project Name**: onekeysetuv
- **Description**: 一键配置uv和python
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-17
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# uv & Python 环境配置工具

一个基于 **CustomTkinter** 的图形化小工具，用来把 `uv` 和 Python 的安装位置、缓存位置、包存储位置
以及国内镜像源一次性配置好，免去手工改环境变量与配置文件。

* 换源：**uv 与 pip 默认使用阿里云**，可在界面上切换清华 / 腾讯云 / 中科大 / 华为云 / 官方源
* 加速：**uv 本体与 Python 解释器使用国内镜像**下载，失败自动切换下一个镜像
* Python 的安装位置由用户自己选择
* 提供 **极简模式**：只指定一个目录，所有内容都收敛在该目录下，可整体拷贝或删除

---

## 一、两种模式

### 极简模式（推荐）

只选一个根目录，其余路径自动推导：

```
<根目录>/
  uv/                         uv 可执行文件          UV_INSTALL_DIR
  python/                     Python 解释器          UV_PYTHON_INSTALL_DIR
  python/bin/                 python3.x 可执行文件   UV_PYTHON_BIN_DIR
  python/user/                用户级包目录           PYTHONUSERBASE
  packages/site-packages/     pip 安装位置           PIP_TARGET（可选）
  packages/uv-tools/          uv 工具/包             UV_TOOL_DIR
  packages/uv-bin/            uv 工具可执行文件      UV_TOOL_BIN_DIR
  cache/uv/                   uv 包缓存              UV_CACHE_DIR
  cache/pip/                  pip 缓存               PIP_CACHE_DIR
  config/                     pip.ini / uv.toml / env.bat / env.ps1 / env.sh
```

该模式安装 Python 时会附加 `--no-registry`，不会往 Windows 注册表写东西；`python3.x.exe`
也会落在 `<根目录>/python/bin` 里，整体拷走即可用。

### 自定义模式

六个位置分别指定：

| 界面项 | 环境变量 |
| --- | --- |
| uv 存储位置 | `UV_INSTALL_DIR` |
| uv 包缓存位置 | `UV_CACHE_DIR` |
| uv 包存储位置 | `UV_TOOL_DIR` + `UV_TOOL_BIN_DIR` |
| Python 安装位置 | `UV_PYTHON_INSTALL_DIR` |
| pip 缓存位置 | `PIP_CACHE_DIR` |
| pip 包存储位置 | `PIP_TARGET`（需勾选开关） |

---

## 二、运行

```powershell
pip install -r requirements.txt
python main.py
```

> 建议在 Windows 上使用。程序只写 **用户级** 环境变量（`HKCU\Environment`），不需要管理员权限。

界面分三个页签：

1. **极简模式** —— 选根目录，下方实时预览将要生成的目录结构
2. **自定义模式** —— 逐个指定位置
3. **环境检测** —— 查看本机 uv / Python / pip 的真实状态，以及目标目录是否存在

底部「配置选项」用于选择镜像源、Python 版本与各种开关，点击 **开始配置** 后按下列步骤执行：

1. 创建目录
2. 写入 `pip.ini` 与 `uv.toml`
3. 写入环境变量（并追加到 PATH）
4. 安装 uv（多镜像依次重试）
5. `uv python install <版本>`（多镜像依次重试）
6. 校验并打印结果

---

## 三、镜像源

| 用途 | 默认 | 候选 |
| --- | --- | --- |
| pip / uv 包索引 | 阿里云 | 清华、腾讯云、中科大、华为云、官方 |
| Python 解释器下载 | CNB（cnb.cool） | 南京大学、ghfast、gh-proxy、moeyy、官方 GitHub |
| uv 本体下载 | CNB（cnb.cool） | ghfast、gh-proxy、moeyy、官方 GitHub |

安装时按候选顺序尝试，第一个成功的会被记录下来；`uv.toml` 中也会写入
`python-install-mirror`，保证以后 `uv python install` 依然走国内镜像。

---

## 四、让配置立即生效

- **新开的终端**：自动带上环境变量（已写入注册表）
- **当前终端**：
  - cmd：`call "<配置文件目录>\env.bat"`
  - PowerShell：`. "<配置文件目录>\env.ps1"`
  - bash/zsh：`source <配置文件目录>/env.sh`

验证：

```powershell
uv --version
uv python list
pip config list
```

---

## 五、开发与打包

```
main.py               入口
app/mirrors.py        镜像源与平台识别
app/plan.py           方案（路径推导、环境变量、配置文件内容、校验）
app/systemenv.py      注册表/shell 环境变量、文件写入与备份
app/installer.py      安装执行器（下载解压、命令执行、多镜像重试）
app/diagnose.py       环境检测报告
app/ui.py             CustomTkinter 界面
build.py              PyInstaller 打包脚本
```

打包：

```powershell
pip install pyinstaller
python build.py              # 单文件 exe，产物在 dist/
python build.py --onedir     # 目录形式，启动更快
```

---

## 六、注意事项

* 所有写文件操作都会在覆盖前生成 `.bak` 备份（带时间戳）。
* 「启用 pip 独立安装位置（`PIP_TARGET`）」会把 `pip install` 的目标改到指定目录，
  可能导致 `python -c "import xxx"` 找不到包，除非同时设置好 `PYTHONPATH`。普通场景建议关闭。
* 「强制重新安装」会覆盖目标位置的 `uv.exe`（覆盖前会备份）。
* 若某个镜像不可用，日志中会看到对应的失败原因，程序会继续尝试下一个。
* `uv.toml` 只写各版本 uv 都稳定支持的键（`cache-dir`、`python-install-mirror`、`[[index]]`），
  Python 安装位置、工具目录等一律通过环境变量提供——因为新版 uv 已不再接受
  `python-install-dir`、`tool-dir` 这类配置文件字段。
* 每写完一次配置，程序都会用本机 uv 自检能否解析该文件；若不能，会自动降级为最小配置甚至删除，
  避免 uv 因配置文件报错而整体不可用。

---

## 七、已知实测结果

在本机（Windows x64）实测：

| 项目 | 结果 |
| --- | --- |
| uv 下载源 | CNB 镜像 `0.12.15` 下载成功 |
| Python 下载镜像 | CNB 镜像安装 `3.12.14` 成功（约 5 秒） |
| 全流程 | 6 个步骤全部通过，耗时约 13 秒 |

> 注意：CNB 镜像的 uv 下载地址不接受 `latest` 别名，必须给具体版本号；程序会先从
> PyPI 索引探测最新版本号，因此源列表里 CNB 排在第一位是安全的。