auto-uv

Automatically use uv run when executing Python scripts. Just type python script.py instead of uv run script.py!

What is This?

auto-uv is a Python package that intercepts script execution and automatically uses uv to run them. Install it once, then forget about it - your scripts just work with proper dependency management.

Installation

pip install auto-uv

That's it! Now when you run python script.py, it automatically uses uv run behind the scenes.

Quick Start

# Install
pip install auto-uv

# Run any script - auto-uv handles the rest
python your_script.py

# Disable temporarily if needed
AUTO_UV_DISABLE=1 python your_script.py

How It Works

The Magic Behind auto-uv

When you install auto-uv, it uses the hatch-autorun plugin to install a .pth file in your Python's site-packages directory:

site-packages/
├── auto_uv.py                      # The main module
├── hatch_autorun_auto_uv.pth       # The magic hook ✨
└── auto_uv-0.1.2.dist-info/

The .pth file contains a single line that runs on Python startup:

import os, sys;exec("__import__('auto_uv').auto_use_uv()")

This means every time Python starts, auto-uv checks if it should intercept:

1. ✅ You're running a script file (not interactive mode or REPL)
2. ✅ You're in a project directory (has pyproject.toml, .venv, or uv.lock)
3. ✅ uv is available on your system
4. ✅ Not already running under uv run (prevents infinite loops)
5. ✅ Not an installed package (doesn't intercept dbt, pytest, etc.)

If all conditions are met, it uses os.execve() to replace the current process with uv run, giving you automatic dependency management.

Why This Works

• Seamless: No need to modify your scripts or remember to use uv run
• Safe: Extensive checks prevent interference with system tools
• Smart: Detects project directories by walking up the tree
• Fast: Uses process replacement (execve), not subprocess spawning

Requirements

• Python 3.9+
• uv installed and in your PATH

Install uv:

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

Configuration

Environment Variables

• AUTO_UV_DISABLE: Set to 1, true, or yes to disable auto-uv
• UV_RUN_ACTIVE: Automatically set by auto-uv (don't set manually)

Disabling auto-uv

# Temporarily disable
AUTO_UV_DISABLE=1 python script.py

# Permanently disable (add to your shell profile)
export AUTO_UV_DISABLE=1

Development

Setup

# Clone the repository
git clone https://github.com/xRiskLab/auto-uv.git
cd auto-uv

# Install with all dev dependencies
uv pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Or use the Makefile
make dev

Testing

# Run tests
make test

# Run tests with act (local GitHub Actions)
make act-test

# Format and lint
make format lint

# Full CI pipeline locally
make ci

Available Make Targets

make help              # Show all available commands
make dev               # Setup development environment
make test              # Run tests
make lint              # Run linters
make format            # Format code
make build             # Build package with uv
make publish-test      # Publish to Test PyPI
make publish           # Publish to PyPI
make clean             # Clean build artifacts
make act-test          # Test with act (local GitHub Actions)
make pre-commit        # Run pre-commit hooks
make commit            # Format, lint, and test before commit

Publishing Manually

# 1. Get token from https://pypi.org/manage/account/token/

# 2. Add to .env file (already in .gitignore)
echo "UV_PUBLISH_TOKEN=pypi-AgE..." >> .env

# 3. Build and publish (Makefile auto-loads .env)
make publish-test

# 4. If successful, publish to PyPI
make publish

Testing with Act

Test GitHub Actions workflows locally before pushing:

# Install act
brew install act  # macOS
# or see: https://github.com/nektos/act

# Optional: Create .env file for secrets (if needed)
echo "GITHUB_TOKEN=your_token_here" > .env

# Test workflows
make act-test           # Quick test
make act-lint           # Test linting
make act-all            # Test everything

Version Management

Bump version using GitHub Actions:

gh workflow run version-bump.yml -f version_type=patch  # 0.1.0 -> 0.1.1
gh workflow run version-bump.yml -f version_type=minor  # 0.1.0 -> 0.2.0
gh workflow run version-bump.yml -f version_type=major  # 0.1.0 -> 1.0.0

Or use the Makefile:

make version-patch  # Bump patch version
make version-minor  # Bump minor version
make version-major  # Bump major version

CI/CD

The project includes three GitHub Actions workflows:

1. test.yml - Run tests on multiple Python versions (3.9-3.12) and OS (Ubuntu, macOS, Windows)
2. workflow.yml - Build and publish to PyPI on release (required name for PyPI)
3. version-bump.yml - Automated version management

Troubleshooting

Installing packages in a uv project

Use uv add to manage dependencies:

# Add runtime dependency
uv add requests

# Add development dependency
uv add --dev pytest

# Add multiple packages
uv add --dev mypy black ruff

Can't install packages

If auto-uv is interfering:

# Option 1: Disable auto-uv temporarily
AUTO_UV_DISABLE=1 pip install package-name

# Option 2: Uninstall auto-uv if not needed
pip uninstall auto-uv

Auto-uv not working

# Check if uv is installed
uv --version

# Check if auto-uv is installed
python -c "import auto_uv; print('Installed')"

# Test manually
python -c "import os; print('UV_RUN_ACTIVE:', os.environ.get('UV_RUN_ACTIVE'))"

Contributing

Contributions welcome! Here's the quick workflow:

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/auto-uv.git
cd auto-uv

# 2. Setup
make dev

# 3. Create branch
git checkout -b feature/your-feature

# 4. Make changes and test
make commit

# 5. Test with act
make act-test

# 6. Push and create PR
git push origin feature/your-feature
gh pr create

See CONTRIBUTING.md for detailed guidelines.

Why auto-uv?

Without auto-uv:

uv run script.py  # Have to remember uv run every time

With auto-uv:

python script.py  # Just works!

Benefits:

• ✅ Seamless workflow
• ✅ Automatic dependency management via uv
• ✅ Zero configuration
• ✅ Easy to disable when needed
• ✅ Safe fallback if uv not available

Inspiration

Inspired by pyauto-dotenv which automatically loads .env files.

License

MIT License - see LICENSE file for details.

Links

• Repository: https://github.com/xRiskLab/auto-uv
• Issues: https://github.com/xRiskLab/auto-uv/issues
• uv: https://github.com/astral-sh/uv
• hatch-autorun: https://github.com/pypa/hatch