python-env

Files (7)

• SKILL.md
• .gitkeep · assets/
• dependency-management.md · references/
• publishing.md · references/
• pyproject-patterns.md · references/
• .gitkeep · scripts/
• skill-report.json

SKILL.md (first lines)

# 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

```bash
# 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

```bash
# 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

```bash
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)

```bash
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

```bash
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

```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**

From aiskillstore/marketplace, MIT.

More from aiskillstore/marketplace