Ansible Role: uv

Install and configure uv - the extremely fast Python package installer and resolver written in Rust by Astral.

Features

• 🚀 Multiple installation methods: Standalone installer (recommended) or pip/pipx
• 📦 Version management: Install latest or pin to specific version
• 👤 Flexible scope: System-wide or user installation
• 🐍 Python management: Install Python versions via uv python install
• 🔧 Global tools: Install CLI tools via uv tool install
• 📁 Virtual environments: Create and configure venvs
• 🎯 Shell completions: Bash, Zsh, and Fish support
• 🔄 Idempotent: Safe to run multiple times

Requirements

• Ansible >= 2.14
• Target: Linux (Debian, Ubuntu, RHEL, CentOS, Fedora) or macOS
• For standalone install: curl (installed automatically on Linux)
• For pip install: Python 3.8+

Installation

From Ansible Galaxy

ansible-galaxy role install francotampieri.uv

In requirements.yml

roles:
  - name: francotampieri.uv
    version: "1.0.1"

Role Variables

Installation Settings

Variable	Default	Description
uv_install_method	standalone	Installation method: standalone or pip
uv_version	latest	Version to install (latest or specific like 0.5.11)
uv_force_install	false	Force reinstallation even if already present
uv_install_scope	user	Installation scope: user or system
uv_install_dir	""	Custom install directory (overrides scope)
uv_user	{{ ansible_user_id }}	User to install uv for

PATH Configuration

Variable	Default	Description
uv_configure_path	true	Add uv to PATH in shell profiles
uv_shell_profiles	[~/.bashrc, ~/.zshrc]	Shell profiles to update

Shell Completions

Variable	Default	Description
uv_install_completions	true	Install shell completions
uv_completion_shells	[bash, zsh]	Shells to install completions for

Python Management

Variable	Default	Description
uv_install_pythons	[]	Python versions to install
uv_default_python	""	Default Python version to pin

Global Tools

Variable	Default	Description
uv_tools	[]	Tools to install globally

Virtual Environments

Variable	Default	Description
uv_venvs	[]	Virtual environments to create

Global Configuration

Variable	Default	Description
uv_configure_global	false	Create global uv configuration
uv_config_path	~/.config/uv/uv.toml	Path to config file
uv_config	{}	Configuration options

Example Playbooks

Basic Installation

- hosts: all
  roles:
    - role: francotampieri.uv

Install Specific Version

- hosts: all
  roles:
    - role: francotampieri.uv
      vars:
        uv_version: "0.5.11"

System-wide Installation

- hosts: all
  become: true
  roles:
    - role: francotampieri.uv
      vars:
        uv_install_scope: system

Full Configuration

- hosts: all
  roles:
    - role: francotampieri.uv
      vars:
        uv_version: latest
        uv_install_scope: user

        # Install Python versions
        uv_install_pythons:
          - "3.12"
          - "3.11"
        uv_default_python: "3.12"

        # Install global tools
        uv_tools:
          - ruff
          - black
          - mypy
          - name: httpie
            version: "3.2.2"

        # Create virtual environments
        uv_venvs:
          - path: /opt/myapp/venv
            python: "3.12"
            requirements: /opt/myapp/requirements.txt
          - path: ~/projects/webapp/venv
            python: "3.11"
            packages:
              - flask
              - gunicorn

        # Global configuration
        uv_configure_global: true
        uv_config:
          python_version: "3.12"
          cache_dir: ~/.cache/uv

CI/CD Pipeline Example

- hosts: ci_runners
  roles:
    - role: ttlab.uv
      vars:
        uv_install_scope: system
        uv_install_pythons:
          - "3.12"
          - "3.11"
          - "3.10"
        uv_tools:
          - ruff
          - pytest

Tags

The role supports the following tags for selective execution:

Tag	Description
uv	All uv tasks
uv-install	Only installation tasks
uv-configure	Configuration tasks (PATH, completions, config)
uv-completions	Only shell completions
uv-python	Only Python installation
uv-tools	Only tool installation
uv-venvs	Only virtual environment creation
uv-verify	Only verification tasks

Example:

# Only install uv, skip configuration
ansible-playbook site.yml --tags uv-install

# Only install Python versions
ansible-playbook site.yml --tags uv-python

Supported Platforms

Platform	Versions
Debian	11, 12, 13
Ubuntu	20.04, 22.04, 24.04
RHEL/CentOS/Rocky	8, 9
Fedora	39, 40
macOS	All supported versions

Dependencies

None.

Testing

This role uses Molecule for testing:

# Install test dependencies
pip install molecule molecule-docker ansible-lint yamllint

# Run tests
molecule test

# Run tests on specific platform
molecule test -s debian

License

MIT

Author

Franco Tampieri - franco@tampieri.info

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Links

• uv Documentation
• Astral
• Ansible Galaxy
• GitHub Repository