uv run: Run a Command in the Project Env

Run tools in the project env, with deps synced automatically.

uv run executes a command in the project’s environment, ensuring it is synced to the lockfile first. CI uses it to run tests and scripts without a separate install step.

What it does

Prepares the environment (syncing from uv.lock if needed), then runs the given command inside it. This guarantees the command sees the locked dependencies.

Common usage

Terminal

uv run pytest
uv run python -m mypackage
uv run --frozen pytest -q

Common CI use: avoid an extra sync step

Because uv run syncs first, a single "uv run --frozen pytest" both installs from the lock and runs the tests. --frozen keeps it strictly reproducible.

Terminal

# One step: install from lock + run tests
uv run --frozen pytest

Related guides

uv sync: Install Exactly What uv.lock PinsHow uv sync makes the environment match uv.lock exactly, the --frozen and --no-dev flags for CI, and the lock… uv lock: Resolve and Write uv.lockHow uv lock resolves the project’s dependencies into uv.lock, the --check flag for CI gates, and the upgrade… python -m pytest: Run Tests with the Project on sys.pathWhy python -m pytest beats a bare pytest in CI, how it adds the current directory to sys.path, and the import…