uv命令找不到的根本原因是安装路径未加入系统PATH环境变量,需将uv.exe所在目录(如%APPDATA%\Python\Python3xx\Scripts\)添加到用户环境变量Path中,并重启终端生效。

uv 命令找不到:PATH 没生效
安装完 uv 却在终端输入 uv --version 提示“command not found”或“无法识别为 cmdlet”,这不是安装失败,而是可执行文件路径没进 PATH。Windows 下常见于 pip install uv 后生成的 uv.exe 在 %APPDATA%\Python\Python3xx\Scripts\,但该路径未被系统加载。
实操建议:
立即学习“Python免费学习笔记(深入)”;
- 先用
pip show uv查Location,往上推一级加\Scripts\就是uv.exe所在目录 - 把该完整路径(如
C:\Users\Alice\AppData\Roaming\Python\Python311\Scripts\)添加到「用户环境变量」的Path中,不是系统变量 - 关掉所有终端再重开,别信“刷新环境变量”的快捷方式——PowerShell / CMD 都要全新启动
- 若用 conda,别在 base 环境装
uv后直接切项目目录跑,uv不会自动继承 conda 的 PATH,要么全局安装,要么激活对应环境再装
uv pip install 失败:Request failed after 3 retries
这个错误本质是网络请求卡在下载环节,和 pip 一样,但 uv 默认重试更激进、超时更短(连接 15s,读取 60s),遇到慢网或镜像同步延迟就容易崩。
实操建议:
立即学习“Python免费学习笔记(深入)”;
- 优先换国内镜像源:
uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ requests - 调大超时参数:
uv pip install --timeout 120 --retries 5 requests(--timeout是总超时,单位秒) - 检查基础连通性:
curl -I https://pypi.org/simple/requests/,如果连不上,说明是代理/DNS/防火墙问题,不是uv自身缺陷 - 避免混用:不要在已配置
pip.conf的机器上期望uv自动读它——uv不兼容 pip 的配置文件,必须显式传参
uv venv 创建失败:Python version not found
uv venv --python 3.12 报错 “Python version 3.12 not found”,不代表你没装 Python 3.12,而是 uv 没在默认路径下扫描到可执行文件。它不依赖 PATH,而是查系统注册表(Windows)、/usr/bin 和 /opt/homebrew/bin(macOS)、/usr/local/bin(Linux)等固定位置。
实操建议:
立即学习“Python免费学习笔记(深入)”;
- 用
which python3.12或Get-Command python3.12(PowerShell)确认真实路径 - 显式传绝对路径:
uv venv --python /opt/homebrew/bin/python3.12 myenv - Windows 用户注意:conda 安装的 Python 通常不在注册表里注册,得手动指定
conda run -n py312 python这类 wrapper 路径,或改用uv venv --python $(Get-Command python3.12).Path(PowerShell) - 别依赖
pylauncher(如py -3.12),uv目前不识别它
uv sync 或 install 后 import 失败:ModuleNotFoundError
明明 uv pip install uvicorn 显示成功,运行时却报 ModuleNotFoundError: No module named 'uvicorn',这大概率是环境错位:你在 A 环境装了包,却在 B 解释器里运行代码。
实操建议:
立即学习“Python免费学习笔记(深入)”;
- 验证当前解释器路径:
python -c "import sys; print(sys.executable)",再对比uv venv创建的.venv/bin/python(或.venv\Scripts\python.exe)是否一致 - PyCharm 用户务必检查右下角 Python 解释器是否指向
.venv目录下的python,而不是系统 Python - 检查
sys.path:python -c "import sys; print('\n'.join(sys.path))",确认输出里包含site-packages路径,且该路径下真有uvicorn/目录 - 版本陷阱:Uvicorn 0.27+ 不支持 Python 3.7,若你用的是旧版 Python,得指定旧版安装:
uv pip install "uvicorn
which python、确认 uv venv 输出的路径、确认代码运行时的 sys.executable —— 三个路径不一致,90% 的 ModuleNotFoundError 就有了答案。


















