PIP_REQUIRE_VIRTUALENV - break setup-python action

[sdolender]

Description:
PIP_REQUIRE_VIRTUALENV - break setup-python action.
setup-python should consider using --isolated option:
https://pip.pypa.io/en/latest/cli/pip/#cmdoption-isolated

Action version:
setup-python@v5

Platform:

• Ubuntu
• macOS
• Windows

Runner type:

• Hosted
• Self-hosted

Tools version:
n/a

Repro steps:
0. Clear ghr _tool dir ( empty caches )

1. Set PIP_REQUIRE_VIRTUALENV=true on self-hosted runner environment
2. Use the following workflow step:

   - uses: actions/setup-python@v5
     with:
       python-version: '3.11'

3. Run the workflow

Expected behavior:
Installed pip packages into local site-packages
<ghr-dir>_work/_tool/Python/3.11.15/x64/lib/python3.11/site-packages

Actual behavior:

  Error: ERROR: Could not find an activated virtualenv (required).
  Error: The process '/usr/bin/bash' failed with exit code 3

[priyagupta108]

Hi @sdolender,
Thank you for creating this issue. We will investigate it and provide feedback as soon as we have some updates.

[gowridurgad]

Hi @sdolender, this happens because your self-hosted runner has PIP_REQUIRE_VIRTUALENV=true set at the environment level. When this variable is enabled, pip refuses to run unless a virtual environment is already activated. By default, pip is bundled with Python, so when a specific Python version is installed, the corresponding version of pip is installed along with it. The actions/setup-python action prepares the requested Python environment and ensures that standard packaging tools such as pip are available and usable.

During actions/setup-python, the setup process may internally invoke pip to prepare Python’s packaging tooling. These operations occur before any workflow step creates or activates a virtual environment. Since PIP_REQUIRE_VIRTUALENV=true is already set on the runner, pip refuses to run outside a virtual environment, which leads to this error.

Regarding the suggestion to use --isolated, that could allow pip to run without being affected by environment variables like PIP_REQUIRE_VIRTUALENV. However, these pip calls happen internally during Python’s installation, so setup-python itself doesn’t directly control them.

To resolve this, avoid enforcing PIP_REQUIRE_VIRTUALENV during the setup-python step, and enable it only when installing project dependencies inside a virtual environment:

- name: Setup Python
  uses: actions/setup-python@v6
  with:
    python-version: "3.11"

- name: Create venv and install dependencies
  run: |
    python -m venv .venv
    source .venv/bin/activate
    pip install -r requirements.txt
  env:
    PIP_REQUIRE_VIRTUALENV: true

If PIP_REQUIRE_VIRTUALENV is globally configured on the runner and cannot be removed, you can temporarily override it (set it to false or unset it) for the setup-python step, and then restore it to true for later steps where pip runs inside a virtual environment.

[gowridurgad]

Hi @sdolender, Just a gentle reminder regarding this issue, If you have any updates or need further assistance, Please let us know.

[gowridurgad]

Hi @sdolender, Just a gentle reminder regarding this issue, If you have any updates or need further assistance, Please let us know.