Skip to content

[AI generated] fix: try next NVML library candidate when nvmlInit fails - #1869

Open
raylei50653 wants to merge 3 commits into
aristocratos:mainfrom
raylei50653:fix/nvml-wsl-fallback
Open

raylei50653 wants to merge 3 commits into
aristocratos:mainfrom
raylei50653:fix/nvml-wsl-fallback

Conversation

@raylei50653

@raylei50653 raylei50653 commented Sep 29, 2026 •

Copy link
Copy Markdown

Closes #1868

[AI generated] This change was developed with Claude Code (Claude Opus 5.5). I reviewed the implementation and tested the affected WSL2 setup.

Problem

On WSL2 with the distro's native nvidia-utils installed, btop may load the native Linux NVML library instead of the working WSL library.

Previously, Gpu::Nvml::init() stopped at the first library that dlopen() could load, even if nvmlInit() failed with Driver Not Loaded. As a result, btop did not detect the NVIDIA GPU despite nvidia-smi working correctly.

Changes

  • Retry NVML candidates: Attempt library loading, symbol resolution, and nvmlInit() for each candidate. If initialization fails, unload the library and continue to the next candidate.
  • Prefer the runtime SONAME: Try libnvidia-ml.so.1 before the unversioned libnvidia-ml.so, which is typically a development symlink. This allows the working WSL library to be selected on the first attempt in the reported setup.
  • Reset function pointers: Clear all NVML function pointers before unloading a failed candidate to avoid leaving dangling pointers.
  • Preserve diagnostics: Retain the existing final failure messages while adding per-candidate initialization diagnostics.

The candidate ordering and function-pointer cleanup also address both hardening suggestions from the review.

Testing

Environment: Arch Linux on WSL2, NVIDIA RTX 5070 Ti Laptop GPU, LD_LIBRARY_PATH unset.

Scenario Result
WSL2 with native nvidia-utils GPU detected; working WSL NVML library mapped
First candidate initializes successfully (bwrap simulation) GPU detected; no unnecessary fallback
Both candidates fail initialization Per-candidate debug logs and existing final failure message
No loadable NVML library Existing informational failure message preserved

Additional validation:

  • btop_test passes.
  • No new compiler warnings reported.
  • GitHub Actions checks pass, including CI, CMake CI, snap build, and security analysis.

Scope

This change is limited to Linux NVML library selection and initialization. It does not alter GPU metric collection after successful initialization.

Gpu::Nvml::init() stopped at the first libnvidia-ml candidate that
dlopen() could load, even if nvmlInit() then failed. On WSL2 with the
native nvidia-utils package installed, libnvidia-ml.so resolves to the
native Linux driver library, which fails with "Driver Not Loaded",
while libnvidia-ml.so.1 resolves to the working WSL library in
/usr/lib/wsl/lib. The GPU box was therefore never shown.

Unload the library and move on to the next candidate when symbol
loading or nvmlInit() fails. Behaviour is unchanged when the first
candidate initializes successfully.

Closes: aristocratos#1868

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@deckstose deckstose added the AI generated Majority of included code is AI generated label Oct 1, 2026
oursland

This comment was marked as spam.

Try libnvidia-ml.so.1 before the unversioned libnvidia-ml.so, which is
usually only a development symlink. On WSL2 this finds the working WSL
library on the first attempt.

Set all NVML function pointers back to nullptr before unloading a
library that failed to load its symbols or to initialize, so none of
them point into an unloaded library.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@raylei50653

Copy link
Copy Markdown
Author

Both points have been addressed. I’ve submitted the latest fixes and updated the PR body.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

AI generated Majority of included code is AI generated

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] NVIDIA GPU not detected on WSL2 when native nvidia-utils is installed (NVML Driver Not Loaded)

3 participants