python-env
Fast Python environment management with uv (10-100x faster than pip). Triggers on: uv, venv, pip, pyproject, python environment, install package, dependencies.
How do I install this agent skill?
npx skills add https://github.com/0xdarkmatter/claude-mods --skill python-envIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides comprehensive instructions for Python environment management using the uv tool. It includes installation steps from the official provider, dependency management patterns, and publishing workflows. All external resources and packages mentioned are standard for the Python ecosystem and originate from well-known sources. No malicious behaviors were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
4 files scanned · No issues
What does this agent skill do?
Python Environment
Fast Python environment management with uv. Prefer the uv project workflow
(uv add / uv sync / uv run) over the uv pip compatibility layer — it
manages pyproject.toml + a lockfile for you and is reproducible.
Quick Commands
| Task | Command |
|---|---|
| Start a project | uv init <name> (app) · uv init --package <name> (installable, src/ layout) |
| Add dependency | uv add httpx |
| Add dev dependency | uv add --dev pytest ruff |
| Remove dependency | uv remove httpx |
| Sync env from lockfile | uv sync |
| Run in project env | uv run pytest |
| Update lockfile | uv lock |
| Install a CLI tool | uv tool install ruff · one-shot: uvx ruff |
| Install a Python | uv python install 3.12 |
Start a Project
# Application (flat layout, no package build)
uv init myapp
# Installable package (src/ layout — separate tests/ that import by name)
uv init --package wordtools
# → src/wordtools/__init__.py, pyproject.toml with build-system
uv init creates pyproject.toml, pins a Python version, and prepares the
project for uv add / uv sync. The --package (src) layout is preferred for
anything with a test suite or that you intend to ship.
Manage Dependencies
# Add runtime deps (writes to [project.dependencies] + updates the lockfile)
uv add "httpx>=0.25" pydantic
# Add dev-only deps (writes to the dev dependency-group)
uv add --dev pytest ruff mypy
# Add with extras
uv add "fastapi[standard]"
# Remove
uv remove httpx
# Install everything from pyproject + uv.lock into .venv (reproducible)
uv sync
# Refresh the lockfile (e.g. after manual pyproject edits)
uv lock
uv creates and manages .venv automatically — you rarely activate it; just
prefix commands with uv run.
Run Code
uv run python script.py # run a script in the project env
uv run pytest # run a tool from the dev group
uv run -- ruff check . # `--` ends uv flag parsing
Never call bare python / pytest / ruff in a uv project — they may resolve
to a different interpreter. Always uv run.
CLI Tools (global, not project deps)
uv tool install ruff # persistent, isolated, on PATH
uv tool upgrade ruff
uvx ruff check . # ephemeral one-shot run, nothing installed
Use uv tool / uvx for developer CLIs (ruff, pre-commit, httpie). Use
uv add only for things your code imports.
Python Versions
uv python install 3.12 # download a managed interpreter
uv python list # show available + installed
uv init --python 3.12 app # pin a project to a version
Check python.org for the current stable (3.14 as of 2026-07; recent releases add
opt-in free-threading and a JIT). 3.11+ is a sensible floor for new projects
(TaskGroup, Self, faster interpreter).
Minimal pyproject.toml
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
"httpx>=0.25",
"pydantic>=2.0",
]
# Dev deps live here; `uv add --dev <pkg>` manages this group.
[dependency-groups]
dev = [
"pytest>=8.0",
"ruff>=0.4",
"mypy>=1.10",
]
Compatibility Layer (uv pip) — last resort
uv pip mirrors pip's interface for environments uv doesn't manage (a hand-made
venv, a legacy requirements.txt, CI that isn't uv-native). It does not
update pyproject.toml or the lockfile — prefer uv add / uv sync whenever
you control the project.
uv venv # bare venv (no project)
uv pip install -r requirements.txt # legacy requirements file
uv pip install -e . # editable install into an unmanaged venv
uv pip compile requirements.in -o requirements.txt # pin a requirements.txt
Troubleshooting
| Issue | Solution |
|---|---|
| "No Python found" | uv python install 3.12 |
| Pin project Python | uv init --python 3.12 or edit requires-python |
| Lock/resolve conflict | uv lock --resolution=lowest-direct to probe, then loosen bounds |
| Stale env after pull | uv sync |
| Cache issues | uv cache clean |
When to Use
- Always use uv over pip — 10-100x faster
uv add/uv remove/uv syncfor project dependencies (notuv pip install)uv runto execute anything inside the project envuv tool install/uvxfor standalone developer CLIsuv piponly for environments uv doesn't manage
Additional Resources
For detailed patterns, load:
./references/pyproject-patterns.md- Full pyproject.toml examples, tool configs./references/dependency-management.md- Lock files, workspaces, private packages./references/publishing.md- PyPI publishing, versioning, CI/CD
See Also
This is a foundation skill with no prerequisites.
Build on this skill:
python-typing-ops- Type hints for projectspython-pytest-ops- Testing infrastructurepython-fastapi-ops- Web API development
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/0xdarkmatter/claude-mods/python-env">View python-env on skillZs</a>