Automatically use uv run when executing Python scripts. Just type python script.py instead of uv run script.py!
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.
pip install auto-uvThat's it! Now when you run python script.py, it automatically uses uv run behind the scenes.
# 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.pyWhen 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:
- ✅ You're running a script file (not interactive mode or REPL)
- ✅ You're in a project directory (has
pyproject.toml,.venv, oruv.lock) - ✅
uvis available on your system - ✅ Not already running under
uv run(prevents infinite loops) - ✅ 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.
- 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
- Python 3.9+
uvinstalled and in your PATH
Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS/Linux
# or
pip install uvAUTO_UV_DISABLE: Set to1,true, oryesto disable auto-uvUV_RUN_ACTIVE: Automatically set by auto-uv (don't set manually)
# Temporarily disable
AUTO_UV_DISABLE=1 python script.py
# Permanently disable (add to your shell profile)
export AUTO_UV_DISABLE=1# 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# 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 cimake 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# 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 publishTest 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 everythingBump 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.0Or use the Makefile:
make version-patch # Bump patch version
make version-minor # Bump minor version
make version-major # Bump major versionThe project includes three GitHub Actions workflows:
- test.yml - Run tests on multiple Python versions (3.9-3.12) and OS (Ubuntu, macOS, Windows)
- workflow.yml - Build and publish to PyPI on release (required name for PyPI)
- version-bump.yml - Automated version management
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 ruffIf 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# 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'))"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 createSee CONTRIBUTING.md for detailed guidelines.
uv run script.py # Have to remember uv run every timepython 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
Inspired by pyauto-dotenv which automatically loads .env files.
MIT License - see LICENSE file for details.
- 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