uvtx

A modern Python task runner built for the uv era.

uvtx solves the common pain points of running Python scripts:

• ✅ No virtual environment activation - uv handles it automatically
• ✅ No PYTHONPATH headaches - configure once, use everywhere
• ✅ No dependency conflicts - isolated per-task environments
• ✅ No configuration duplication - task inheritance and profiles

Features

Core Features

• 🚀 Zero setup: Leverages uv for automatic dependency management
• 📦 PYTHONPATH management: Configure paths once, use everywhere
• 🎯 Task definitions: Reusable tasks with dependencies, env vars, and arguments
• 📜 PEP 723 support: Scripts can declare inline dependencies
• ⚡ Parallel execution: Run multiple tasks concurrently with smart failure handling
• 🔄 Pipelines: Multi-stage workflows perfect for CI/CD
• 🎭 Conditional execution: Run tasks based on platform, environment, or files
• 👀 Watch mode: Auto-rerun tasks when files change

Advanced Features

• 🎨 Profiles: Environment-specific configurations (dev/staging/prod)
• 🔗 Task inheritance: Extend tasks to eliminate duplication
• 🏷️ Aliases: Multiple names for the same task
• 🪝 Task hooks: Run scripts before/after tasks for setup/teardown
• 🔖 Task tags: Organize and filter tasks by categories
• 📂 Task categories: Logical grouping for tasks (testing, build, deploy)
• 🚨 Global error handler: Centralized error recovery across all tasks
• 💾 Built-in env vars: Automatic context variables (project root, git info, CI detection)
• 🔒 Private tasks: Hide implementation details (tasks starting with _)
• 🌍 .env file support: Load environment variables from files
• 🔍 Config discovery: Automatically finds uvtx.toml in parent directories
• 🔤 Task variables/templating: Reusable {variable} syntax in task definitions
• 🏃 Global runner prefix: Automatically prepend commands (e.g., dotenv run, docker exec)
• 📝 Output redirection: Send stdout/stderr to files or /dev/null
• ⚡ Inline tasks: Run commands directly from CLI without config file
• 🔄 Retry logic: Automatic retry with exponential backoff for flaky tasks
• 📊 Dependency visualization: View task graphs in ASCII, DOT, or Mermaid formats

Installation

Prerequisites

uvtx requires uv to be installed. Install it first:

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip
pip install uv

Install uvtx

# Using uv (recommended)
uv tool install uvtx

# Using pip
pip install uvtx

# From source
git clone https://github.com/mikeleppane/uvtx
cd uvtx
uv pip install -e .

Quick Start

1. Create a uvtx.toml in your project root:

[project]
name = "my-project"

[env]
PYTHONPATH = ["src"]

[tasks.hello]
description = "Print hello world"
cmd = "python -c 'print(\"Hello from uvtx!\")'"

[tasks.test]
description = "Run tests"
cmd = "pytest"
dependencies = ["pytest", "pytest-cov"]
pythonpath = ["src", "tests"]

2. Run a task:

uvtx run hello
uvtx run test

Core Concepts

Config File Location

uvtx looks for configuration in:

1. uvtx.toml (preferred)
2. pyproject.toml under [tool.uvtx]

It searches from the current directory upward.

Profiles

Profiles let you define environment-specific configurations without duplicating tasks. Perfect for dev/staging/prod environments.

[project]
name = "my-api"
default_profile = "dev"  # Used when no --profile specified

# Global .env files (loaded first)
env_files = [".env"]

[env]
API_URL = "http://localhost:8000"  # Default/fallback

# Development profile
[profiles.dev]
env = { DEBUG = "1", LOG_LEVEL = "debug" }
env_files = [".env.dev"]  # Profile-specific .env
python = "3.12"

# CI profile
[profiles.ci]
env = { CI = "1", LOG_LEVEL = "info" }
dependencies = { testing = ["pytest>=8.0", "coverage"] }

# Production profile
[profiles.prod]
env = { LOG_LEVEL = "error", WORKERS = "4" }
env_files = [".env.prod"]
python = "3.11"

[tasks.serve]
script = "src/server.py"
dependencies = ["fastapi", "uvicorn"]

Usage:

# Use default profile (dev)
uvtx run serve

# Explicit profile
uvtx run serve --profile prod

# Override via environment
UVR_PROFILE=ci uvtx run test

Priority order (later overrides earlier):

1. Global .env files
2. Global env vars
3. Profile .env files
4. Profile env vars

Task Inheritance

Reduce duplication by extending tasks. Child tasks inherit and override parent configuration.

# Base task
[tasks.test]
description = "Run tests"
cmd = "pytest"
dependencies = ["pytest"]
pythonpath = ["src", "tests"]

# Inherit and override
[tasks.test-verbose]
extend = "test"
description = "Run tests with verbose output"
args = ["-v", "-s"]  # Adds to parent args

[tasks.test-coverage]
extend = "test"
description = "Run tests with coverage"
dependencies = ["pytest-cov"]  # Merged with parent
args = ["--cov=src", "--cov-report=html"]

[tasks.test-watch]
extend = "test-verbose"
description = "Watch and run tests"
cmd = "pytest-watch"  # Overrides parent cmd

Inheritance rules:

• Override: script, cmd, cwd, timeout, python, description
• Merge (no duplicates): dependencies, pythonpath, depends_on
• Concatenate: args (parent args + child args)
• Merge dicts: env (child overrides parent keys)

Aliases and Private Tasks

Aliases provide shortcuts for frequently used tasks:

[tasks.format]
description = "Format all code"
cmd = "ruff format src/ tests/"
dependencies = ["ruff"]
aliases = ["f", "fmt"]  # Run with: uvtx run f

[tasks.lint]
description = "Lint code"
cmd = "ruff check src/"
dependencies = ["ruff"]
aliases = ["l"]

[tasks.typecheck]
description = "Type check code"
cmd = "mypy src/"
dependencies = ["mypy"]
aliases = ["t", "types"]

Private tasks (start with _) are hidden from uvtx list:

[tasks._setup-db]
description = "Internal: Initialize database"
script = "scripts/setup_db.py"

[tasks._cleanup]
description = "Internal: Clean temp files"
cmd = "rm -rf .cache __pycache__"

[tasks.ci]
description = "Run CI checks"
depends_on = ["_setup-db", "test", "_cleanup"]
# _setup-db and _cleanup won't show in `uvtx list`
# but are still runnable: uvtx run _setup-db

List tasks:

uvtx list              # Shows public tasks with aliases
uvtx list --all        # Shows private tasks too
uvtx list --verbose    # Shows full details

Configuration Reference

Full Example

[project]
name = "my-project"
python = "3.12"  # Default Python version

[env]
# Global environment variables
PYTHONPATH = ["src", "lib"]
DATABASE_URL = "postgres://localhost/dev"

[dependencies]
# Named dependency groups
common = ["requests", "pydantic>=2.0"]
testing = ["pytest", "pytest-cov"]
linting = ["ruff", "mypy"]

[tasks.format]
description = "Format code"
cmd = "ruff format src/"
dependencies = ["ruff"]

[tasks.lint]
description = "Run linting"
cmd = "ruff check src/"
dependencies = ["linting"]

[tasks.typecheck]
description = "Run type checking"
cmd = "mypy src/"
dependencies = ["mypy"]
env = { MYPYPATH = "src" }

[tasks.test]
description = "Run tests"
script = "scripts/run_tests.py"
dependencies = ["testing"]
pythonpath = ["src", "tests"]
args = ["--verbose"]

[tasks.check]
description = "Run all checks"
depends_on = ["lint", "typecheck", "test"]
parallel = true  # Run dependencies in parallel

[pipelines.ci]
description = "CI pipeline"
on_failure = "fail-fast"  # or "wait", "continue"
output = "buffered"  # or "interleaved"
stages = [
    { tasks = ["lint", "typecheck"], parallel = true },
    { tasks = ["test"] },
]

Task Options

Option	Type	Description
description	string	Task description shown in uvtx list
script	string	Path to Python script to run
cmd	string	Shell command to run
args	list	Default arguments passed to script/cmd
dependencies	list	Package dependencies or group names (e.g., ["pytest"], ["testing"])
env	table	Task-specific environment variables
pythonpath	list	Additional paths to add to PYTHONPATH
depends_on	list	Other tasks that must run first
parallel	bool	Run depends_on tasks in parallel (default: false)
python	string	Python version for this task (e.g., "3.12")
cwd	string	Working directory for task execution
timeout	int	Timeout in seconds (task killed if exceeded)
ignore_errors	bool	Continue even if task fails (exit code 0)
condition	table	Declarative conditions for task execution
condition_script	string	Script that must exit 0 for task to run
extend	string	Parent task to inherit from
aliases	list	Alternative names for this task
tags	list	Tags for organizing and filtering tasks
category	string	Logical category for the task (testing, build, deploy)
before_task

Task Hooks

Hooks allow you to run scripts before or after task execution, perfect for setup/teardown, notifications, or cleanup:

[tasks.deploy]
description = "Deploy application"
script = "scripts/deploy.py"
before_task = "scripts/pre_deploy_check.py"   # Pre-flight checks
after_success = "scripts/notify_success.sh"    # Send success notification
after_failure = "scripts/rollback.sh"          # Rollback on failure
after_task = "scripts/cleanup.py"              # Always cleanup temp files

Hook Types:

• before_task: Runs before the task. If it fails, the task is skipped.
• after_success: Runs only if the task succeeds (exit code 0).
• after_failure: Runs only if the task fails (exit code != 0).
• after_task: Always runs after the task, regardless of success or failure.

Hook Environment Variables:

Hooks receive these special environment variables:

• UVR_TASK_NAME: Name of the task being run
• UVR_HOOK_TYPE: Type of hook (before_task, after_success, etc.)
• UVR_TASK_EXIT_CODE: Exit code of the task (for after hooks)

Hooks also inherit the task's e