uv Troubleshooting

uv 故障排除

Purpose

目的

Master troubleshooting uv issues, from dependency resolution failures to environment setup problems. Quickly diagnose errors and get your project working again.

掌握uv问题的故障排除方法，从依赖解析失败到环境配置问题。快速诊断错误，让你的项目恢复正常运行。

Quick Start

快速开始

Get help immediately when uv fails:

bash

undefined

当uv执行失败时立即获取帮助：

bash

undefined

See what's happening

查看详细执行过程

uv sync --verbose

Clear cache if something seems broken

若出现异常，清理缓存

uv cache clean

Force fresh resolution

强制重新解析依赖

uv lock --upgrade

Check your Python installation

检查Python安装情况

uv python list


Most issues resolve with verbose output + cache clearing + fresh resolution.

uv python list


大多数问题都可以通过查看详细输出+清理缓存+重新解析依赖来解决。

Instructions

操作步骤

Step 1: Understanding uv Error Categories

步骤1：了解uv错误分类

uv errors fall into these categories:

Resolution Errors (versions don't match)

error: Failed to resolve version for package X
error: Incompatible versions required

Environment Errors (Python not found)

error: Python X.Y not found
error: No python version available

Cache Errors (corrupted data)

error: Cache is corrupted
error: Invalid cache entry

Network Errors (can't reach PyPI)

error: Failed to fetch from PyPI
error: Connection timeout

Lock File Errors (conflicts)

error: Lock file out of sync with pyproject.toml

uv错误主要分为以下几类：

解析错误（版本不匹配）

error: Failed to resolve version for package X
error: Incompatible versions required

环境错误（未找到Python）

error: Python X.Y not found
error: No python version available

缓存错误（数据损坏）

error: Cache is corrupted
error: Invalid cache entry

网络错误（无法连接PyPI）

error: Failed to fetch from PyPI
error: Connection timeout

锁文件错误（冲突）

error: Lock file out of sync with pyproject.toml

Step 2: Debugging Dependency Resolution

步骤2：调试依赖解析问题

Problem: "No matching version found"

bash

undefined

问题："未找到匹配版本"

bash

undefined

Get verbose output to see what's being checked

查看详细输出，了解检查过程

uv add package-name --verbose

Error message might say:

错误信息可能显示：

error: No version of package-name found matching >=2.0,<2.5

Solutions:

解决方案：

1. Check available versions

1. 查看可用版本

pip index versions package-name

2. Loosen version constraint

2. 放宽版本约束

uv add "package-name>=2.0" # Remove upper bound

uv add "package-name>=2.0" # 移除版本上限

3. Check if package was renamed

3. 检查包是否已重命名

Search PyPI website or use:

访问PyPI官网或使用以下命令：

pip search package-name


**Problem: "Incompatible dependencies"**

```bash

pip search package-name


**问题："依赖不兼容"**

```bash

Show resolution process

查看解析过程

uv add --dry-run package-a package-b

If both can't work together, you'll see:

若两者无法兼容，会显示：

error: Incompatible versions required for package-c:

package-a requires package-c>=1.0,<2.0

package-b requires package-c>=2.0,<3.0

Solutions:

解决方案：

1. Try newer versions that might be compatible

1. 尝试使用可能兼容的新版本

uv add "package-a>=2.0" "package-b>=3.0"

2. Use separate dependency groups

2. 使用独立的依赖组

uv add --group ml-cpu torch-cpu uv add --group ml-gpu torch-gpu

Install one group at a time

每次仅安装一个依赖组

3. Contact maintainers if genuinely incompatible

3. 若确实不兼容，联系包维护者


**Problem: "Source conflicts"**

```bash


**问题："源冲突"**

```bash

Check your PyPI sources

检查PyPI源配置

cat pyproject.toml | grep -A 5 "[tool.uv]"

If using custom PyPI index:

若使用自定义PyPI索引：

Error might occur due to missing packages in custom index

错误可能源于自定义索引中缺少对应包

Solutions:

解决方案：

1. Add fallback to PyPI

1. 添加PyPI作为备用源

[tool.uv] index-url = "https://custom.index.com/simple" extra-index-urls = ["https://pypi.org/simple"]

2. Or specify per-package

2. 或为单个包指定源

uv add --index-url https://custom.index.com requests

undefined

uv add --index-url https://custom.index.com requests

undefined

Step 3: Handling Version Conflicts

步骤3：处理版本冲突

Problem: Lock file out of sync

bash

undefined

问题：锁文件不同步

bash

undefined

Error message:

错误信息：

error: The lock file uv.lock is out of sync with pyproject.toml

Solution 1: Regenerate lock file

解决方案1：重新生成锁文件

uv lock

Solution 2: Force fresh resolution

解决方案2：强制重新解析

uv lock --upgrade

Solution 3: Clear cache and retry

解决方案3：清理缓存后重试

uv cache clean uv lock


**Problem: Pre-release versions causing issues**

```bash

uv cache clean uv lock


**问题：预发布版本导致异常**

```bash

If you see error about pre-release being unavailable:

若出现预发布版本不可用的错误：

error: pre-release version not found

Check what's actually available

查看实际可用版本

uv python list | grep 3.13

Solution: Pin stable version instead

解决方案：固定稳定版本

uv python pin 3.12 # Use stable instead of rc


**Problem: Transitive dependency conflict**

```bash

uv python pin 3.12 # 使用稳定版而非候选发布版


**问题：间接依赖冲突**

```bash

When indirect dependencies conflict:

当间接依赖冲突时：

package-a requires indirect-dep==1.0

package-b requires indirect-dep==2.0

Show dependency tree to find issue

查看依赖树定位问题

uv tree

Solution: Update one of the direct dependencies

解决方案：更新其中一个直接依赖

Find which needs updating with:

使用以下命令查找需要更新的包：

uv tree | grep indirect-dep

Then update the direct package

然后更新直接依赖包

uv add "package-a>=2.0" # Might have updated indirect-dep

undefined

uv add "package-a>=2.0" # 新版本可能已更新间接依赖

undefined

Step 4: Cache Issues and Recovery

步骤4：缓存问题与恢复

Problem: Cache corruption

bash

undefined

问题：缓存损坏

bash

undefined

Symptoms:

症状：

- Same operations fail each time

- 相同操作反复失败

- Error messages about cache

- 出现缓存相关错误信息

- Slow/hanging operations

- 操作缓慢或挂起

Solution 1: Clean specific cache

解决方案1：清理指定缓存

uv cache clean all # Clean everything uv cache clean --all # Alternative syntax

uv cache clean all # 清理所有缓存 uv cache clean --all # 替代语法

Solution 2: Check cache location

解决方案2：查看缓存位置

uv cache dir

On macOS: /Users/username/Library/Caches/uv

macOS系统：/Users/username/Library/Caches/uv

On Linux: ~/.cache/uv

Linux系统：~/.cache/uv

On Windows: %APPDATA%\uv\cache

Windows系统：%APPDATA%\uv\cache

Solution 3: Manual cache deletion (if needed)

解决方案3：手动删除缓存（必要时）

rm -rf ~/.cache/uv # Linux/macOS rmdir %APPDATA%\uv\cache # Windows


**Problem: Cache growing too large**

```bash

rm -rf ~/.cache/uv # Linux/macOS rmdir %APPDATA%\uv\cache # Windows


**问题：缓存体积过大**

```bash

Check cache size

查看缓存大小

du -sh ~/.cache/uv

Or on macOS/Linux with homebrew-installed uv:

或在macOS/Linux系统中，若通过homebrew安装uv：

du -sh ~/Library/Caches/uv

Solution: Clean unused cache

解决方案：清理未使用的缓存

uv cache clean all

Prevention: Set cache limits in pyproject.toml

预防措施：在pyproject.toml中设置缓存限制

[tool.uv]

Limit cache to 2GB (example)

示例：限制缓存为2GB

cache-size = "2G"

undefined

cache-size = "2G"

undefined

Step 5: Environment and Python Issues

步骤5：环境与Python问题

Problem: "Python X.Y not found"

bash

undefined

问题："未找到Python X.Y"

bash

undefined

Error: Python 3.12 not found in PATH

错误：Python 3.12 not found in PATH

Step 1: Check what Python is available

步骤1：查看系统中可用的Python

which python python --version

Step 2: List uv's Python installations

步骤2：查看uv管理的Python版本

uv python list

Step 3: Install needed version

步骤3：安装所需版本

uv python install 3.12

Step 4: Pin for project if needed

步骤4：为项目固定Python版本（可选）

uv python pin 3.12

Step 5: Verify

步骤5：验证

uv python list python --version


**Problem: Wrong Python version being used**

```bash

uv python list python --version


**问题：使用了错误的Python版本**

```bash

Check which Python uv is using

查看uv当前使用的Python版本

python --version

Check project pinning

查看项目固定的版本

cat .python-version

Solutions:

解决方案：

1. Pin correct version

1. 固定正确的版本

uv python pin 3.12

2. Or remove pin to use system Python

2. 或移除版本固定，使用系统Python

rm .python-version

3. Check PATH if system Python is wrong

3. 若系统Python版本错误，检查PATH配置

echo $PATH

Make sure correct Python directory is first

确保正确的Python目录位于PATH首位


**Problem: Virtual environment is broken**

```bash


**问题：虚拟环境损坏**

```bash

Symptoms:

症状：

- Python imports fail

- Python导入失败

- Packages installed but not found

- 已安装的包无法找到

- Mysterious import errors

- 出现不明原因的导入错误

Solution: Resync with fresh venv

解决方案：重新同步并生成新的虚拟环境

uv sync --reinstall # Reinstall all packages

uv sync --reinstall # 重新安装所有包

Or:

或：

uv sync --force-reinstall-all # Force all packages to reinstall

undefined

uv sync --force-reinstall-all # 强制重新安装所有包

undefined

Step 6: Performance Optimization

步骤6：性能优化

Problem: Dependency resolution is slow

bash

undefined

问题：依赖解析缓慢

bash

undefined

Example:

uv sync

takes 5+ minutes

示例：

uv sync

耗时超过5分钟

Solution 1: Use frozen lock file

解决方案1：使用冻结的锁文件

uv sync --frozen # Don't resolve, use existing lock

uv sync --frozen # 不进行解析，直接使用现有锁文件

Solution 2: Build cache

解决方案2：构建缓存

Run

uv lock

once, then

uv sync

uses it

先执行

uv lock

，后续

uv sync

将使用缓存

Solution 3: Check for large transitive deps

解决方案3：检查是否存在大量间接依赖

uv tree | wc -l # Count total dependencies

uv tree | wc -l # 统计总依赖数

If >100, you might have large dependency tree

若超过100个，说明依赖树过大

Solution 4: Disable network operations

解决方案4：禁用网络操作

uv sync --offline # Use only cached packages


**Problem: Large lock files**

```bash

uv sync --offline # 仅使用缓存中的包


**问题：锁文件过大**

```bash

If uv.lock is very large (>10MB)

若uv.lock体积过大（超过10MB）

wc -l uv.lock

Solution 1: Trim unnecessary dependencies

解决方案1：移除不必要的依赖

uv remove unused-package

Solution 2: Use extras to split optional deps

解决方案2：使用extras拆分可选依赖

Instead of: uv add package[all]

替代：uv add package[all]

Do: uv add package # Core only

改为：uv add package # 仅安装核心功能

Then: uv add --group extras package[optional]

然后：uv add --group extras package[optional]

Solution 3: Check for duplicate versions

解决方案3：检查是否存在重复版本

grep "^name = " uv.lock | sort | uniq -c | sort -rn

If duplicates, investigate with:

若存在重复版本，使用以下命令排查：

uv tree | grep duplicate-package

undefined

uv tree | grep duplicate-package

undefined

Step 7: Platform-Specific Issues

步骤7：特定平台问题

Problem: Windows PATH issues

bash

undefined

问题：Windows系统PATH配置问题

bash

undefined

After installing uv, command not found

安装uv后，提示命令未找到

Solution 1: Restart terminal/PowerShell

解决方案1：重启终端/PowerShell

uv installer modifies PATH, needs restart

uv安装程序会修改PATH，需重启终端生效

Solution 2: Add to PATH manually

解决方案2：手动添加到PATH

Find where uv installed:

查找uv安装路径：

where uv # Command prompt Get-Command uv # PowerShell

where uv # 命令提示符 Get-Command uv # PowerShell

Solution 3: Use full path

解决方案3：使用完整路径执行

c:\Users\username.cargo\bin\uv --version


**Problem: macOS/Linux permissions**

```bash

c:\Users\username.cargo\bin\uv --version


**问题：macOS/Linux系统权限问题**

```bash

Error: Permission denied

错误：Permission denied

"Cannot install to /usr/local/bin"

Solution 1: Use proper installation

解决方案1：使用官方安装脚本

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

Solution 2: Check shell configuration

解决方案2：检查Shell配置

echo $PATH

Ensure ~/.cargo/bin is in PATH

确保~/.cargo/bin已添加到PATH

Solution 3: Fix permissions

解决方案3：修复权限

chmod +x ~/.cargo/bin/uv


**Problem: Docker build failures**

```bash

chmod +x ~/.cargo/bin/uv


**问题：Docker构建失败**

```bash

Error building Docker image with uv

使用uv构建Docker镜像时出错

Solution: Use official uv Docker image

解决方案：使用官方uv Docker镜像

FROM ghcr.io/astral-sh/uv:latest as base FROM python:3.12-slim

Or install uv in existing image

或在现有镜像中安装uv

FROM python:3.12-slim RUN curl -LsSf https://astral.sh/uv/install.sh | sh ENV PATH="/root/.cargo/bin:$PATH" COPY . /app WORKDIR /app RUN uv sync

undefined

FROM python:3.12-slim RUN curl -LsSf https://astral.sh/uv/install.sh | sh ENV PATH="/root/.cargo/bin:$PATH" COPY . /app WORKDIR /app RUN uv sync

undefined

Examples

示例

Example 1: Debugging "No Python Found" Error

示例1：调试"未找到Python"错误

bash

undefined

bash

undefined

Error when running uv sync:

执行uv sync时出现错误：

error: Failed to find python interpreter

Step 1: Check what's available

步骤1：查看可用Python版本

uv python list

Output shows no Python installed

输出显示未安装任何Python

Step 2: Install Python 3.12

步骤2：安装Python 3.12

uv python install 3.12

Step 3: Pin for project

步骤3：为项目固定Python版本

uv python pin 3.12

Step 4: Verify

步骤4：验证

uv python list uv sync

Result: Project now works

结果：项目恢复正常运行

undefined

undefined

Example 2: Resolving Version Conflicts

示例2：解决版本冲突

bash

undefined

bash

undefined

Error when adding two packages:

添加两个包时出现错误：

uv add package-a package-b

error: Incompatible versions required for shared-lib

Step 1: Get details with dry-run

步骤1：使用dry-run查看详细信息

uv add --dry-run package-a package-b

Shows: package-a needs shared-lib>=1.0,<2.0

显示：package-a需要shared-lib>=1.0,<2.0

package-b needs shared-lib>=2.0

package-b需要shared-lib>=2.0

Step 2: Check newer versions

步骤2：尝试使用新版本

uv add --dry-run "package-a>=2.0" "package-b>=3.0"

Works! Newer versions are compatible

成功！新版本兼容

Step 3: Add both

步骤3：添加两个包

uv add "package-a>=2.0" "package-b>=3.0"

Result: Both packages installed with compatible versions

结果：两个包均已安装，且版本兼容

undefined

undefined

Example 3: Fixing Cache Corruption

示例3：修复缓存损坏

bash

undefined

bash

undefined

Symptoms:

症状：

- Operations fail inconsistently

- 操作失败情况不一致

- Error: "Cannot read cache entry"

- 错误："Cannot read cache entry"

- uv hanging on sync

- uv sync时挂起

Step 1: Identify cache issue

步骤1：确认缓存问题

uv sync --verbose

Shows cache corruption

显示缓存损坏

Step 2: Clean cache

步骤2：清理缓存

uv cache clean all

Step 3: Rebuild

步骤3：重新构建

uv lock --upgrade uv sync

Result: Everything works again

结果：所有操作恢复正常

undefined

undefined

Example 4: Windows PATH Setup

示例4：Windows系统PATH配置

bash

undefined

bash

undefined

After installing uv on Windows

在Windows系统安装uv后

Error: "uv is not recognized as an internal or external command"

错误："uv is not recognized as an internal or external command"

Step 1: Verify uv is installed

步骤1：验证uv是否已安装

where uv

Returns: C:\Users\username.cargo\bin\uv

返回：C:\Users\username.cargo\bin\uv

Step 2: Check if in PATH

步骤2：检查是否已添加到PATH

$env:PATH -split ";" | Select-String ".cargo"

Should show .cargo path

应显示.cargo路径

Step 3: If missing, restart terminal

步骤3：若未添加，重启终端

Close and reopen PowerShell/Terminal

关闭并重新打开PowerShell/终端

Step 4: Verify works

步骤4：验证是否可用

uv --version

uv 0.1.39

undefined

undefined

Example 5: Docker Build Optimization

示例5：Docker构建优化

dockerfile

undefined

dockerfile

undefined

Original that fails

原构建脚本失败

FROM python:3.12-slim RUN pip install uv COPY . /app WORKDIR /app RUN uv sync # Fails: uv not in PATH

FROM python:3.12-slim RUN pip install uv COPY . /app WORKDIR /app RUN uv sync # 失败：uv不在PATH中

Fixed version

修复后的版本

FROM python:3.12-slim COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv COPY . /app WORKDIR /app RUN uv sync

Result: Docker image builds successfully

结果：Docker镜像构建成功

undefined

undefined

Example 6: Troubleshooting Slow Resolution

示例6：排查解析缓慢问题

bash

undefined

bash

undefined

Problem: uv sync takes 2 minutes

问题：uv sync耗时2分钟

Project has 150+ transitive dependencies

项目包含150+个间接依赖

Step 1: Check what's slow

步骤1：定位缓慢环节

time uv lock --upgrade

Takes 90 seconds

耗时90秒

Step 2: Use frozen lock after first sync

步骤2：首次同步后使用冻结锁文件

uv sync --frozen

Takes 5 seconds (no resolution)

耗时5秒（无需解析）

Step 3: Only update lock when intentional

步骤3：仅在需要时更新锁文件

uv lock --upgrade # Do this occasionally uv sync --frozen # Use this normally

uv lock --upgrade # 定期执行此命令 uv sync --frozen # 日常开发使用此命令

Result: 18x faster sync for daily development

结果：日常同步速度提升18倍

undefined

undefined

Requirements

前置要求

uv installed (install:

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

)

Python 3.8+ available (for basic operations)
Internet connection (for downloading packages and resolving versions)
Git (optional, for version control and rollback)
Understanding of dependency resolution (recommended)

已安装uv（安装命令：

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

）

Python 3.8+（基础操作所需）
网络连接（用于下载包和解析版本）
Git（可选，用于版本控制和回滚）
了解依赖解析原理（推荐）

uv-troubleshooting

Original

Translation

uv Troubleshooting

uv 故障排除

Purpose

目的

Quick Start

快速开始

See what's happening

查看详细执行过程

Clear cache if something seems broken

若出现异常，清理缓存

Force fresh resolution

强制重新解析依赖

Check your Python installation

检查Python安装情况

Instructions

操作步骤

Step 1: Understanding uv Error Categories

步骤1：了解uv错误分类

Step 2: Debugging Dependency Resolution

步骤2：调试依赖解析问题

Get verbose output to see what's being checked

查看详细输出，了解检查过程

Error message might say:

错误信息可能显示：

error: No version of package-name found matching >=2.0,<2.5

error: No version of package-name found matching >=2.0,<2.5

Solutions:

解决方案：

1. Check available versions

1. 查看可用版本

2. Loosen version constraint

2. 放宽版本约束

3. Check if package was renamed

3. 检查包是否已重命名

Search PyPI website or use:

访问PyPI官网或使用以下命令：

Show resolution process

查看解析过程

If both can't work together, you'll see:

若两者无法兼容，会显示：

error: Incompatible versions required for package-c:

error: Incompatible versions required for package-c:

package-a requires package-c>=1.0,<2.0

package-a requires package-c>=1.0,<2.0

package-b requires package-c>=2.0,<3.0

package-b requires package-c>=2.0,<3.0

Solutions:

解决方案：

1. Try newer versions that might be compatible

1. 尝试使用可能兼容的新版本

2. Use separate dependency groups

2. 使用独立的依赖组

Install one group at a time

每次仅安装一个依赖组

3. Contact maintainers if genuinely incompatible

3. 若确实不兼容，联系包维护者

Check your PyPI sources

检查PyPI源配置

If using custom PyPI index:

若使用自定义PyPI索引：

Error might occur due to missing packages in custom index

错误可能源于自定义索引中缺少对应包

Solutions:

解决方案：

1. Add fallback to PyPI

1. 添加PyPI作为备用源

2. Or specify per-package

2. 或为单个包指定源

Step 3: Handling Version Conflicts

步骤3：处理版本冲突

Error message:

错误信息：

error: The lock file uv.lock is out of sync with pyproject.toml

error: The lock file uv.lock is out of sync with pyproject.toml

Solution 1: Regenerate lock file

解决方案1：重新生成锁文件

Solution 2: Force fresh resolution