Handling of virtual environments
================================

By default, wox creates virtual environments using Python’s built-in venv module.
This guarantees compatibility down to Python 3.3, and avoids external dependencies such as virtualenv.

When ``with_uv`` is enabled, wox switches to uv for environment creation.
In that case, environments are created using uv’s bundled virtualenv implementation.

.. note::

    If ``with_uv`` is enabled but the selected Python version is not supported by uv or by virtualenv, wox automatically falls back to creating the environment with venv.

    This fallback is seamless and requires no additional configuration.

Minimum suggested version for venv handled by wox
-------------------------------------------------

Wox supports virtual environments created with Python >= 3.3, but it is designed to work best with Python >= 3.6.

This is because wox relies on the modern dependency resolver introduced in pip 20. It is technically available before Python 3.6 but significantly more stable and mature with pip 21.

Moreover, starting with Python 3.6, Python 2 support is removed from the ecosystem, marking the end of the transitional "2-to-3" era that wox does not aim to support.

In practice, Python 3.6+ provides a more predictable and robust dependency-installation environment.

.. _manually_created_venv:

Wox and manually created virtual environment
--------------------------------------------

Wox does not require the virtual environments to be created by itself.

If you manually create a virtual environment inside .wox and reference its name in a task's envlist, wox will automatically detects it and uses it for the session exactly as if wox had created it.

This includes dependency installation and command execution.

How to use wox without relying on Python virtual environments?
--------------------------------------------------------------

Wox can operate even when the environment in .wox is not a Python virtual environment at all.

If a directory inside .wox is listed in envlist, wox assumes that you have performed all the required setup yourself, which skips the python discovery and the virtual environment creation process completely.

The environment remains fully usable during the session, but it will not benefit from Wox’s internal discovery mechanisms. You must explicitly specify any required paths or commands yourself in the commands setting of the wox.toml.
