How do I know which interpreter uv is using?

Run 'uv run python --version' to see the actual interpreter uv selects.

What if the pinned version differs from the system Python?

Update the pin (echo '3.13' > .python-version), then remove the old venv (rm -rf .venv), create a new one (uv venv), and resync (uv sync --all-extras).

What should I do if import still fails after installation?

Verify the uv context interpreter with 'uv run python --version', check installation with 'uv pip show ', and test import with 'uv run python -c 'import ; print( .__version__)''. Ensure compatibility with the pinned Python version.

environment-triage

npx machina-cli add skill parcadei/Continuous-Claude-v3/environment-triage --openclaw

Files (1)

SKILL.md

1.1 KB

Environment Triage

When uv sync or pip install behaves unexpectedly, check the actual interpreter.

Pattern

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

DO

# What uv ACTUALLY uses
uv run python --version

# What's pinned (this controls uv)
cat .python-version

# Confirm package is installed
uv pip show <package>

# Confirm import works in uv context
uv run python -c "import <package>; print(<package>.__version__)"

Common Fix

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

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

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

Source

git clone https://github.com/parcadei/Continuous-Claude-v3/blob/main/.claude/skills/environment-triage/SKILL.mdView on GitHub

Overview

Environment Triage helps you confirm which Python interpreter uv actually uses when installs or syncs fail. It prevents silent mismatches between the system Python, virtual environments, and the pinned interpreter in .python-version.

How This Skill Works

The skill guides you to check the interpreter uv uses, inspect the pinned version, and validate package availability within the uv context. Technically, you query uv's Python version, read .python-version, inspect installed packages with uv pip show, and perform a quick import test using uv run python -c 'import <package>; print(<package>.__version__)'.

When to Use It

When uv sync or uv install behaves unexpectedly and you suspect an interpreter mismatch.
When the system Python differs from the interpreter selected by uv in a venv.
When .python-version pins a version that conflicts with required dependencies.
When a package import fails in the uv context despite a successful install.
When optional deps require Python 3.12+ but .python-version pins an older version

Quick Start

Step 1: uv run python --version
Step 2: cat .python-version
Step 3: uv run python -c 'import <package>; print(<package>.__version__)'

Best Practices

Don’t trust python3 --version when using uv; verify with uv run python --version.
Always check which interpreter uv is actually using before debugging install issues.
Confirm the pinned version matches your target (cat .python-version) and adjust if needed.
Verify installation and importability in the uv context (uv pip show <pkg> and import test).
If needed, update the pinned version and recreate the environment: echo '3.13' > .python-version; rm -rf .venv; uv venv; uv sync --all-extras

Example Use Cases

uv run python --version reveals Python 3.11, but .python-version pins 3.12, causing import errors.
Installing numpy with uv fails when the interpreter is not the one the package expects; running uv run python -c 'import numpy; print(numpy.__version__)' confirms.
Pushing an update to .python-version without recreating the venv leads to mismatched site-packages.
A failed install appears successful but uv pip show numpy shows no installation in the uv context.
Updating .python-version to 3.13 and running 'rm -rf .venv && uv venv && uv sync --all-extras' resolves the issue

Frequently Asked Questions

Add this skill to your agents