Why use uv instead of pip/python?

To keep the project environment and dependency state under uv management, improving reproducibility and isolation.

Can I mix uv with traditional pip workflows?

Gradually migrate to uv for consistency; direct pip/python calls bypass uv's environment and can cause drift.

What if a needed tool isn't available via uv add?

If uv add can't install it, evaluate alternatives or wait for uv support; the goal is to keep as much tooling under uv as possible to preserve reproducibility.

python-uv-project-setup

Scanned

npx machina-cli add skill narumiruna/agent-skills/python-uv-project-setup --openclaw

Files (1)

SKILL.md

1.7 KB

Python uv Project Setup

Overview

Use uv for environments, dependency management, and command execution. Core principle: always install and run through uv, not pip/python directly.

Non-Negotiable Rules

Install dependencies with uv add (never pip install).
Run commands with uv run (never direct python or pytest).

Quick Reference

Task	Command
Initialize project	`uv init <name>`
Add dependency	`uv add <package>`
Add dev dependency	`uv add --dev <package>`
Run Python	`uv run python <file.py>`
Run pytest	`uv run pytest`
Sync deps	`uv sync`

Workflow

Project setup (package)

uv init my-project
cd my-project
uv add loguru typer
uv add --dev ruff pytest pytest-cov ty

Script setup (single file)

If you are working with a script, still install with uv and run via uv:

uv add fastapi
uv run python script.py

Example

Issue: "Missing fastapi. Tests fail."

Fix:

uv add fastapi
uv run pytest

Common Mistakes

Running pip install first and only switching to uv after it fails.
Running python or pytest directly instead of uv run.

Rationalizations to Reject

Excuse	Reality
"pip install is faster for a quick fix"	It bypasses the project environment and drifts from uv-managed state.
"I can run python/pytest directly this once"	Direct runs skip uv's environment and can break reproducibility.

Red Flags

Any instruction that uses pip install, python, or pytest directly.

Source

git clone https://github.com/narumiruna/agent-skills/blob/main/skills/python-uv-project-setup/SKILL.mdView on GitHub

Overview

Use uv for environments, dependency management, and command execution. Core principle: always install and run through uv, not pip/python directly.

How This Skill Works

Uv replaces direct pip/python usage with uv commands. You install dependencies with uv add, initialize projects with uv init, and run Python or tests with uv run, keeping everything within uv's environment management.

When to Use It

Starting a new Python project and setup
Adding dependencies or dev dependencies via uv add
Running Python scripts or pytest through uv run
Ensuring reproducible environments across machines or CI
Converting an existing workflow to uv-managed commands

Quick Start

Step 1: uv init <name>
Step 2: uv add <package> or uv add --dev <package>
Step 3: uv run <command>

Best Practices

Always install dependencies with uv add; never pip install
Run Python and pytest through uv run
Initialize projects with uv init to standardize setup
Use uv sync to lock and align dependencies
Avoid mixing direct pip/python/pytest calls with uv

Example Use Cases

uv init my-project; uv add loguru typer; uv add --dev ruff pytest pytest-cov ty
uv add fastapi; uv run python script.py
uv add fastapi; uv run pytest
Initialize project, add deps, and run tests in CI with uv run pytest
After changing dependencies, run uv sync to update the lock state

Frequently Asked Questions

Add this skill to your agents