environment-triage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Environment Triage

环境问题排查

When

uv sync

pip install

behaves unexpectedly, check the actual interpreter.

当

uv sync

或

pip install

表现异常时，请检查实际使用的解释器。

Pattern

规律

System Python is not authoritative if uv/venv selects a different interpreter.

如果uv/venv选择了不同的解释器，系统Python将不再是权威的。

DO

正确做法

bash

undefined

bash

undefined

What uv ACTUALLY uses

uv实际使用的解释器版本

uv run python --version

What's pinned (this controls uv)

固定的Python版本（此配置控制uv）

cat .python-version

Confirm package is installed

确认包已安装

uv pip show <package>

Confirm import works in uv context

确认在uv环境中可以正常导入包

uv run python -c "import <package>; print(<package>.version)"

undefined

uv run python -c "import <package>; print(<package>.version)"

undefined

Common Fix

常见修复方案

If optional deps require Python 3.12+ but .python-version is 3.11:

bash

echo "3.13" > .python-version
rm -rf .venv && uv venv && uv sync --all-extras

如果可选依赖要求Python 3.12+但.python-version配置的是3.11：

bash

echo "3.13" > .python-version
rm -rf .venv && uv venv && uv sync --all-extras

DON'T

错误做法

Trust
```
python3 --version
```
when using uv
Assume install succeeded without verifying import
Debug further before checking interpreter version

使用uv时，不要轻信
```
python3 --version
```
的结果
不要在未验证导入的情况下假设安装已成功
不要在未检查解释器版本的情况下进行进一步调试

Source Sessions

问题案例

2243c067: symbolica-agentica skipped due to
```
python_version >= 3.12
```
marker, but uv was using 3.11
4784f390: agentica import failures traced to wrong interpreter

2243c067：symbolica-agentica因
```
python_version >= 3.12
```
标记被跳过，但uv实际使用的是3.11版本
4784f390：agentica导入失败问题追踪到是使用了错误的解释器