Python `error: externally-managed-environment` during installation

[zjeffer]

I'm setting up a clang-tidy action for the Waybar repo: https://github.com/zjeffer/Waybar/blob/90208f8c17b815e3a50265e679a184354f5dcd9b/.github/workflows/clang-tidy.yml

I'm using Waybar's debian image as a base because I need to configure with meson before running clang-tidy, to generate compile_commands.json. I noticed that with this image, I had to install both sudo and python3-pip to fix errors during the installation.

After this, there's one error left when it runs python3 -m pip install -r "$GITHUB_ACTION_PATH/requirements.txt" in this repo's action.yaml:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    
    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.
    
    See /usr/share/doc/python3.11/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.
Error: Process completed with exit code 1.

I was wondering if this error could be fixed by using a venv for all OSes, not just macOS like what you're doing here: https://github.com/cpp-linter/cpp-linter-action/blob/v2/action.yml#L130-L134. Would that fix this error?

[2bndy5]

I'm under the impression that that message only happens when pip install is invoked with sudo permission or as the root user. If the runner is somehow configured in such a way, then using a python venv probably won't fix the problem.

[zjeffer]

Just tested by copying the action file to my own branch: https://github.com/zjeffer/Waybar/actions/runs/7129251571/job/19412927359

It seems to install & run cpp-linter correctly now, but I'm getting different errors now:

symbolic link created /github/home/.local/bin/clang-tidy
Run . "$GITHUB_ACTION_PATH/venv/bin/activate"
  
INFO:CPP Linter:Appending submodule to ignored paths: package/archlinux
INFO:CPP Linter:Ignoring the following paths/files:
	./.github
	./package/archlinux
INFO:CPP Linter:processing push event
Event json from the runner
Get list of specified source files
  INFO:CPP Linter:Fetching files list from url: https://api.github.com/repos/zjeffer/Waybar/commits/5f69d6e8675038369414f1b0d65320cd5dc14b32
  INFO:CPP Linter:Giving attention to the following files:
  	src/modules/hyprland/workspaces.cpp
Performing checkup on src/modules/hyprland/workspaces.cpp
  INFO:CPP Linter:Running "clang-tidy-17 --export-fixes=.cpp-linter_cache/clang_tidy_output.yml -p /__w/Waybar/Waybar/build --line-filter=[{"name": "src/modules/hyprland/workspaces.cpp", "lines": [[50, 51]]}] --extra-arg= src/modules/hyprland/workspaces.cpp"
  DEBUG:CPP Linter:Output from clang-tidy:
  ../include/bar.hpp:16:10: error: 'xdg-output-unstable-v1-client-protocol.h' file not found [clang-diagnostic-error]
     16 | #include "xdg-output-unstable-v1-client-protocol.h"
        |          ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
  DEBUG:CPP Linter:clang-tidy made the following summary:
  13697 warnings and 2 errors generated.
  Error while processing /__w/Waybar/Waybar/src/modules/hyprland/workspaces.cpp.
  Suppressed 13697 warnings (13670 in non-user code, 17 due to line filter, 10 with check filters).
  Use -header-filter=.* to display errors from all non-system headers. Use -system-headers to display errors from system headers as well.
  Found compiler error(s).

but I guess I should open a new issue for that?

---

Is there a downside to using venv's for every OS, instead of just for macOS?

[zjeffer]

I'm under the impression that that message only happens when pip install is invoked with sudo permission or as the root user. If the runner is somehow configured in such a way, then using a python venv probably won't fix the problem.

I don't think I'm necessarily invoking it with sudo or as the root user explicitly, I think it's because I'm using the debian image as a base. I don't get the errors when running on the default ubuntu-latest image (which maybe is configured to not run as root by default?)

What if you install the python requirements with --user?

[2bndy5]

What if you install the python requirements with --user?

Maybe that would work. I can't say for certain if I don't know what exactly is causing the error. I've never actually tried using pip install as the root user.

You could make a fork and try it by changing the uses: field

    - uses: zjeffer/cpp-linter-action@test-branch-name
      name: clang-tidy
      id: clang-tidy-check
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        PIP_NO_CACHE_DIR: false
      with:
        style: '' # empty string => don't do clang-format checks here, we do them in clang-format.yml
        files-changed-only: true # only check files that have changed
        lines-changed-only: true # only check lines that have changed
        tidy-checks: '' # empty string => use the .clang-tidy file
        version: '17' # clang-tools version
        database: 'build' # path to the compile_commands.json file

If the --user option is feasible fix then we could accept that change.

---

The new error you encountered seems similar to cpp-linter/cpp-linter#30 which details known problems with the relative paths that Meson puts in the compilation database file; relative paths used in the database are not friendly with clang-tidy.

[zjeffer]

If the --user option is feasible fix then we could accept that change.

Great, I'll test this and make a PR.

The new error you encountered seems similar to cpp-linter/cpp-linter#30 which details known problems with the relative paths that Meson puts in the compilation database file; relative paths used in the database are not friendly with clang-tidy.

I think it's also because I need to build the entire project, not just configure it with Meson, to generate those xdg files. I'll test this too.

EDIT: building the entire project fixes that missing header file.

[zjeffer]

Adding --user to python3 -m pip install didn't fix it: https://github.com/zjeffer/Waybar/actions/runs/7129953996/job/19415221902

[2bndy5]

It would be nice to see the output of echo "hello, $USER" when used within this docker.

• If it prints "hello, runner", then a venv would certainly be in order.
• If it prints "hello, root", then the docker needs to be configured with a non-root user.

Our previous attempt to use a python venv didn't work well because we were trying to avoid altering the PATH variable in the runner's context. It may be time to revisit that idea.

[2bndy5]

Looking more into PEP668:

This PEP proposes a mechanism for a Python installation to communicate to tools like pip that its global package installation context is managed by some means external to Python, such as an OS package manager. It specifies that Python-specific package management tools should neither install nor remove packages into the interpreter’s global context, by default, and should instead guide the end user towards using a virtual environment.

Meaning, ALL pip usage should now be done within a venv. I see why they (pip as of v23.0) chose to add this notification, but I think it should've been a warning level notification, not an error (at least for a limited probation period).

This also means the ubuntu-latest runner image is still using an older pip version (v22.0.2 as of this writing) which is why the error hasn't surfaced yet (in our test or as user-feedback).

[2bndy5]

@zjeffer I just pushed an attempt to fix this with a py venv. Please try our use-py-venv branch:

    - uses: cpp-linter/cpp-linter-action@use-py-venv

and let me know if that works better with the docker image (please include link to workflow run).

[zjeffer]

It would be nice to see the output of echo "hello, $USER" when used within this docker.

• $USER outputs an empty string
• id outputs id: uid=0(root) gid=0(root) groups=0(root)

Please try our use-py-venv branch:
- uses: cpp-linter/cpp-linter-action@use-py-venv
and let me know if that works better with the docker image (please include link to workflow run).

https://github.com/zjeffer/Waybar/actions/runs/7133837047/job/19427361234

Run /__t/Python/3.11.6/x64/bin/python -m venv "$env:GITHUB_ACTION_PATH/venv"
  /__t/Python/3.11.6/x64/bin/python -m venv "$env:GITHUB_ACTION_PATH/venv"
  if ("Linux"  -ceq "macOS" -or "Linux" -ceq "Linux") {
    Invoke-Expression -Command "$env:GITHUB_ACTION_PATH/venv/bin/Activate.ps1"
  }
  else {
    Invoke-Expression -Command "$env:GITHUB_ACTION_PATH/venv/Scripts/Activate.ps1"
  }
  pip install -r "$env:GITHUB_ACTION_PATH/requirements.txt"
  clang-tools -i 17 -b
  shell: pwsh -command ". '{0}'"
  env:
    GITHUB_TOKEN: ***
    PIP_NO_CACHE_DIR: false
OCI runtime exec failed: exec failed: unable to start container process: exec: "pwsh": executable file not found in $PATH: unknown
Error: Process completed with exit code 126.

Why use powershell instead of bash?
You also don't have to use a different shell, instead of source (which doesn't work with sh, but it does with bash), you can replace it with . and keep using sh.

[2bndy5]

Why use powershell instead of bash?

TL;DR Because bash can't properly handle windows style paths. C:\path\to\python.exe is used as C:pathotpython.exe. There's actually another problem related to this bash behavior when passing the absolute path to the compilation database on Windows runners.

I'm installing python v3.11 but not adding it to the system PATH (to avoid altering with the user's env). Instead I'm getting the python-3.11 exe path from the actions/setup-python output variable, which uses the path style appropriate to the runner's OS...

"pwsh": executable file not found in $PATH: unknown

That certainly is a problem. You can install pwsh in Linux, but it may not be desirable if only to use this action. I might be able to remedy this by ensuring pwsh is installed in the "Install Linux deps" step.

FWIW, self-hosted windows runners might have the same problem using bash. Thankfully git on windows ships with it's own dist of bash.exe, but no guarantee that its added to the system PATH.

---

I'm starting to lean toward calling this an edge case since the docker image you're using is running as root.