home / skills / 0xdarkmatter / claude-mods / python-env

python-env skill

needs review

This skill speeds up Python project setup by fast environment management with uv, enabling instant venvs, rapid package installs, and reliable dependency

npx playbooks add skill 0xdarkmatter/claude-mods --skill python-env

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

2.5 KB

---
name: python-env
description: "Fast Python environment management with uv (10-100x faster than pip). Triggers on: uv, venv, pip, pyproject, python environment, install package, dependencies."
compatibility: "Requires uv CLI tool. Install: curl -LsSf https://astral.sh/uv/install.sh | sh"
allowed-tools: "Bash"
depends-on: []
related-skills: []
---

# Python Environment

Fast Python environment management with uv.

## Quick Commands

| Task | Command |
|------|---------|
| Create venv | `uv venv` |
| Install package | `uv pip install requests` |
| Install from requirements | `uv pip install -r requirements.txt` |
| Run script | `uv run python script.py` |
| Show installed | `uv pip list` |

## Virtual Environment

```bash
# Create venv (instant)
uv venv

# Create with specific Python
uv venv --python 3.11

# Activate (or use uv run)
source .venv/bin/activate  # Unix
.venv\Scripts\activate     # Windows
```

## Package Installation

```bash
# Single package
uv pip install requests

# Multiple packages
uv pip install flask sqlalchemy pytest

# With extras
uv pip install "fastapi[all]"

# Version constraints
uv pip install "django>=4.0,<5.0"

# Uninstall
uv pip uninstall requests
```

## Minimal pyproject.toml

```toml
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "httpx>=0.25",
    "pydantic>=2.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "ruff>=0.1",
]
```

## Project Setup Checklist

```bash
mkdir my-project && cd my-project
uv venv
# Create pyproject.toml
uv pip install -e ".[dev]"
uv pip list
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "No Python found" | `uv python install 3.11` |
| Wrong Python version | `uv venv --python 3.11` |
| Conflicting deps | `uv pip compile --resolver=backtracking` |
| Cache issues | `uv cache clean` |

## When to Use

- **Always** use uv over pip for speed
- Creating virtual environments
- Installing packages
- Managing dependencies
- Running scripts in project context

## 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-patterns` - Type hints for projects
- `python-pytest-patterns` - Testing infrastructure
- `python-fastapi-patterns` - Web API development

Overview

This skill provides fast Python environment management using uv, delivering 10-100x faster package operations than pip. It streamlines creating virtual environments, installing packages, running scripts, and managing dependencies from pyproject configurations. The workflow is focused on speed, reproducibility, and common developer tasks for local projects.

How this skill works

The skill wraps common environment tasks as uv commands: uv venv to create virtual environments, uv pip ... to install/uninstall/list packages, and uv run to execute scripts inside the project context. It can target specific Python versions, handle requirements or pyproject dependencies, and includes helpers for resolving conflicts and cleaning caches.

When to use it

Setting up a new project and creating an isolated virtual environment quickly
Installing, upgrading, or removing packages with much faster install times
Running scripts inside the project environment without manual activation (uv run)
Bootstrapping a development environment from pyproject.toml or requirements.txt
Troubleshooting dependency conflicts or cleaning cached artifacts

Best practices

Create a venv per project with uv venv (or uv venv --python X.Y for a specific interpreter)
Declare dependencies in pyproject.toml for reproducible installs and use optional-dependencies for dev tooling
Use uv pip install -r requirements.txt for pinned builds, and uv pip install -e '.[dev]' during setup
Use uv pip compile --resolver=backtracking when facing conflicting dependency constraints
Prefer uv run to execute scripts in the environment instead of manual activate/deactivate steps

Example use cases

Bootstrap a new app: mkdir my-project && cd my-project; uv venv; create pyproject.toml; uv pip install -e '.[dev]'
Quickly install runtime and dev dependencies: uv pip install fastapi 'uvicorn[standard]' pytest ruff
Run tests inside the project environment without activating: uv run pytest tests/
Resolve a complex dependency conflict: uv pip compile --resolver=backtracking then uv pip install -r .venv/requirements.txt
Recover from a missing interpreter: uv python install 3.11 and recreate the venv with uv venv --python 3.11

FAQ

How do I activate a uv-created venv?

You can source .venv/bin/activate on Unix or use .venv\Scripts\activate on Windows, or simply use uv run to execute commands without manual activation.

Can I install packages from pyproject.toml?

Yes. Declare dependencies in pyproject.toml and install them with uv pip install -e '.[dev]' or by using uv pip with appropriate flags to target the project metadata.

What if uv reports a missing Python interpreter?

Install a matching interpreter with uv python install 3.11 (or your desired version) and recreate the venv with uv venv --python 3.11.