Skip to content

Feature request: Prefer 'uv' to create virtualenv for playbook execution if available #7

@jorge-romero

Description

@jorge-romero

Summary

Please add an optional feature to prefer the uv tool (when available on PATH) to create the virtual environment used to run playbooks/tests. The idea is to detect uv at runtime and use it to create the venv where the playbook is executed, falling back to the existing venv logic when uv is not present.

Background / motivation

Currently the framework sets up a virtual environment via an internal implementation (python3 -m venv / venv module). Some environments (CI, developer machines) install uv (or other venv helper tools) which may provide faster env creation, better reproducible environment handling, caching, and centralized management. Allowing uv to be used when present improves performance and integrates with developer workflows.

Proposed behaviour

  • At startup of PlaybookRunner.setup_virtualenv() detect whether an executable named uv is available via shutil.which("uv") (or equivalent).
  • If uv is present, call it to create the virtual environment at the expected path (the same path the runner currently uses), and then continue with the current bootstrapping (installing requirements, calling module_mocker.setup_mocks(), etc.).
  • If uv is not present, fall back to the existing python3 -m venv / builtin behaviour.
  • The change should be opt-in via config flag if you prefer explicit control, but safe default is: prefer uv when present.

Compatibility and safety

  • Backwards compatible: if uv is not installed, behaviour is unchanged.
  • Keep existing semantics for use_virtualenv marker and virtualenv.path.
  • Ensure error handling: if uv fails to create the env, fall back to builtin venv and surface a warning; do not abort tests silently.

Implementation notes (suggested)

  • Add a small helper in core/playbook_runner.py that encapsulates env creation and abstracts over uv vs builtin venv.
  • Unit tests: mock shutil.which and assert the runner calls uv when available and falls back otherwise.
  • Integration test: if CI image can include uv optionally, verify the created env works and module_mocker.setup_mocks() is still invoked correctly.

Why this will help

  • Better developer ergonomics for teams that adopt uv.
  • Potentially faster environment creation and improved caching/reproducibility.

Open questions

  • Does the project want this behaviour to be automatic or opt-in via a config flag? I suggested automatic detection with a config override.

/cc @maintainers

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions