uv-workflow

uv Workflow

Use uv as the entrypoint for Python execution and standalone script management.

Core Rules

Do not run python or python3 as the shell entrypoint.
Translate direct Python commands into the closest uv form before running them.
python inside uv run ... is acceptable because uv controls interpreter selection and environment setup.
When sandboxed or when cache writes may fail, set UV_CACHE_DIR to a writable temporary directory before running uv.
For standalone PEP 723 scripts, let uv manage inline metadata. Do not hand-edit metadata blocks.

Command Map

Need	Use
Run a script	`uv run path/to/script.py`
Run a module	`uv run -m package.module`
Run a one-liner	`uv run python -c "print('hello')"`
Run a dependency-provided tool	`uv run tool-name`
Add an ad hoc dependency	`uv run --with package python -c "..."`
Run tests	`uv run pytest` or `uv run -m pytest`
Create a standalone script	`uv init --script path/to/script.py`
Add a script dependency	`uv add --script path/to/script.py package`
Remove a script dependency	`uv remove --script path/to/script.py package`

Standalone Script Workflow

For a new single-file script:

Initialize it with uv init --script path/to/script.py.
Add dependencies with uv add --script path/to/script.py <package>.
Edit the Python code normally.
Run it with uv run path/to/script.py.
Remove dependencies with uv remove --script path/to/script.py <package>.

Use uv init --script even when the script already exists conceptually and only needs to be created on disk.

Scope Boundary

Use this skill for Python execution, Python tools, tests, one-liners, and standalone PEP 723 scripts.

If the task is about a full Python project with pyproject.toml, use project-oriented uv commands instead of script-specific metadata commands. Keep uv as the entrypoint, but do not force uv init --script or uv add --script onto project workflows.

More Patterns

Read references/uv-command-patterns.md for PowerShell and POSIX cache setup, script lifecycle examples, and project-vs-script guidance.