Parallel setup-python (Python installation) fails on custom Windows machine that runs multiple self-hosted runners?

[McDic]

Why are you starting this discussion?

Question

What GitHub Actions topic or product is this about?

Actions Runner

Discussion Details

Not sure if this is an actual bug or my mistake by misunderstanding.

name: Linting with pre-commit

on:
  push:
    branches:
      - "**"
    tags-ignore:
      - "**"
  pull_request:
    branches:
      - "**"

jobs:
  pre-commit:
    runs-on: [self-hosted, Windows]
    steps:
      - uses: actions/checkout@v5
      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.14.2t"
          cache: "pip"
      - name: Install Python dependencies
        run: |
          pip install -r requirements-dev.txt

Above yml is some minimal subset Python workflow examples that I am running. Doing actions/checkout, actions/setup-python and do something like pre-commit or python -m unittest.

When I re-run individual task sequentially, this looks working. However, when I submit an empty commit to trigger multiple Python workflows at once, sometimes Python installation(setup-python stage) fails with some logs like following:

  Execute installation script
  Check if Python hostedtoolcache folder exist...
  
  Check if current Python version is installed...
  
  Python3.14 (x64-freethreaded) was found in C:\github-action-runners\runner2\_work\_tool\Python...
  
  Deleting C:\github-action-runners\runner2\_work\_tool\Python\3.14.2\x64-freethreaded...
  
  Remove registry entries for Python 3.14(x64-freethreaded)...
  
  VERBOSE: Performing the operation "Remove Key" on target "Item: 
  HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Installer\UserData\S-1-5-18\Products\(REDACTED)".
  VERBOSE: Performing the operation "Remove Key" on target "Item: 
  HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Installer\UserData\S-1-5-18\Products\(REDACTED)".
  
  VERBOSE: Performing the operation "Remove Key" on target "Item: 
  HKEY_CLASSES_ROOT\Installer\Products\(REDACTED)".
  
  VERBOSE: Performing the operation "Remove Key" on target "Item: 
  HKEY_CLASSES_ROOT\Installer\Products\(REDACTED)".
  
  VERBOSE: Performing the operation "Remove Key" on target "Item: 
  HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\(REDACTED)".
  
  VERBOSE: Performing the operation "Remove Key" on target "Item: 
  HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\(REDACTED)".
  
  Create Python 3.14.2 folder in C:\github-action-runners\runner2\_work\_tool\Python
  
  Copy Python binaries to C:\github-action-runners\runner2\_work\_tool\Python\3.14.2\x64-freethreaded
  
  Install Python 3.14.2 in C:\github-action-runners\runner2\_work\_tool\Python...
  
  Error: Error happened during Python installation
  At C:\github-action-runners\runner2\_work\_temp\(REDACTED)\setup.ps1:126 char:5
  +     Throw "Error happened during Python installation"
  +     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      + CategoryInfo          : OperationStopped: (Error happened ...on installation:String) [], RuntimeException
      + FullyQualifiedErrorId : Error happened during Python installation
  Error: The process 'C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe' failed with exit code 1

... and I cannot see what's exactly happened on error even with debug log enabled. I am giving administrator permission on each runner services.

My guess for why these error happening is that setup-python tries to manage some global values like registry keys, and when multiple runners try to manage same thing at same time, something goes wrong.

Is there any guide for this, or is this a bug from actions/setup-python?

[Tamanna-Sharma8]

[samus-aran]

Hi @Tamanna-Sharma8 ,

We’ve clarified our stance on using generative AI tools like ChatGPT within our Community via this announcement. Please review the guidelines to ensure your post meets them as failure to adhere to those rules can result in action taken by our moderator team.  You can read our updated Code of Conduct and the announcement for more details. Thank you for helping us maintain an authentic and beneficial space for everyone.

[pratikrath126]

Parallel failures on custom Windows machines with multiple self-hosted runners are often due to race conditions or file locking when runners concurrently access the same tool cache.
To resolve this:

1. Use unique tool caches: Configure each runner to use a distinct .
2. Locking mechanisms: Implement a lock (e.g., using a PowerShell script) to ensure only one runner performs the installation at a time.
3. Pre-install Python: Avoid dynamic installation by pre-installing the required Python versions on your runner images.
   This ensures stability and prevents runners from interfering with each other's environment setup.

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬

[AstroJr0]

Damn, This is a Race Condition caused by how actions/setup-python interacts with a shared Windows environment. I think on self-hosted Windows runners, the action attempts to modify global resources (HKEY\_LOCAL\_MACHINE and the _tool cache) which cannot be safely accessed by multiple processes simultaneously.

When multiple workflows trigger at once, each runner instance tries to 'clean' or 'install' Python to the same shared directory and registry keys.

1. Runner A starts deleting registry entries to ensure a fresh install.
2. Runner B starts, finds the files/keys missing or locked by Runner A, and throws a RuntimeException.
3. Because the Windows Registry is a global singleton, providing admin permissions actually makes the collision worse, as it allows the runners to successfully interfere with system-wide keys.

🛠 Recommended Solutions

1. Pre-install Python on the Runner (Best for Stability)

Since this is a self-hosted runner, you should manually install Python 3.14.2 on the host machine's OS. Once it is in the system PATH, remove the actions/setup-python step from your YAML.

• Benefit: Eliminates the installation step entirely, removing the point of failure.

2. Implement a Concurrency Group

Force the workflows to wait for each other so that only one runner handles the Python setup at a time.

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

3. Use Unique Tool Caches

If you are running multiple runner services on the same machine, configure each runner with its own AGENT_TOOLSDIRECTORY.

• Action: Set a unique environment variable for each runner service so they use C:\runner1\_work\_tool, C:\runner2\_work\_tool, etc. Note that some Python installers may still collide on global registry keys.
  Verdict: This is a known limitation of using setup-python on high-concurrency Windows self-hosted environments. Moving the dependency management to the machine level (Pre-installation) is the standard architectural fix.

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬