run-python-with-uv

name	run-python-with-uv
description	Run, create, and troubleshoot Python projects, one-off commands, and standalone scripts with uv instead of python3, pip, or manually managed virtual environments. Use when Codex needs to execute Python, add or lock dependencies, use PEP 723 inline metadata, make a portable Python utility, avoid a repository .venv, or fix uv cache and environment-discovery problems.

Run Python With uv

Use uv as the Python entry point. Read repository instructions first and preserve the project's existing dependency and lockfile conventions.

Choose an Execution Mode

1. Use the project environment for repository code:

   uv run python path/to/script.py
   uv run pytest
   

2. Use an ephemeral dependency for a one-off command:

   uv run --no-project --with 'requests<3' python -c 'import requests; ...'
   

3. Use PEP 723 inline metadata for a reusable standalone script. Prefer this for tools that must not depend on the caller's project or .venv:

   #!/usr/bin/env -S uv run --script
   # /// script
   # requires-python = ">=3.12"
   # dependencies = ["requests<3"]
   # ///
   

4. Use uv run --isolated ... when testing a project in a fresh environment. Do not confuse this with a standalone PEP 723 tool.

Manage Dependencies

• Add project dependencies with uv add PACKAGE.
• Add development dependencies with uv add --dev PACKAGE.
• Update and verify the lock with uv lock.
• Require an unchanged lock in CI or reproducible runs with uv run --locked.
• Add script dependencies with uv add --script SCRIPT PACKAGE.
• Lock a standalone script with uv lock --script SCRIPT.
• Avoid pip install into the system interpreter or an unmanaged environment.

Apply uv Command Rules

• Put uv options before the command or script:

  uv run --python 3.12 -- script.py --script-argument
  

• Use --no-project when a one-off command must ignore a nearby pyproject.toml.

• Prefer PEP 723 metadata over a long list of repeated --with arguments.

• Set a writable cache location when the default cache is unavailable:

  UV_CACHE_DIR=/tmp/uv-cache uv run ...
  

• Expect the first run to resolve dependencies and possibly download Python. Subsequent runs reuse uv's cache.

Verify Work

Run the checks already configured by the repository. Typical commands are:

uv run ruff check .
uv run ty check
uv run pytest

Read references/uv-patterns.md for command selection, portable-tool examples, cache troubleshooting, and reproducibility details.