docs(cuda): use Windows-native BNB_CUDA_VERSION guidance

[peter941221]

docs(cuda): use Windows-native BNB_CUDA_VERSION guidance

Summary

This updates CUDA override guidance to use platform-appropriate shell commands on Windows and documents the local source-build case where the toolkit version used for the native DLL does not match the CUDA version bundled with the installed PyTorch wheel.

Problem

On Windows, bitsandbytes currently emits Unix-style guidance such as unset BNB_CUDA_VERSION and export BNB_CUDA_VERSION=... from bitsandbytes/cextension.py.

That is misleading for Windows users, especially in the common local-source-build workflow where:

• PyTorch reports one CUDA version for wheel compatibility (for example cu130)
• the local CUDA toolkit used for compilation is newer (for example CUDA 13.2)
• the built DLL therefore has a different suffix (for example libbitsandbytes_cuda132.dll)

In that situation, users may need BNB_CUDA_VERSION to point bitsandbytes at the locally built DLL, but the current warning text tells them to use Unix shell syntax even on Windows.

Change

• add a small helper in bitsandbytes/cextension.py that formats env-var guidance per platform
• use set VAR=... / set VAR= on Windows instead of export / unset
• add targeted tests for the platform-specific guidance
• add a Windows source-build note to docs/source/installation.mdx covering the local toolkit / PyTorch CUDA version mismatch case

Validation

Validated on Windows with:

• local source build using CUDA 13.2 -> libbitsandbytes_cuda132.dll
• local PyTorch reporting 2.12.0+cu130
• pytest tests/test_cuda_setup_evaluator.py -q

The targeted tests pass, and the Windows warning text now suggests set BNB_CUDA_VERSION=... and set BNB_CUDA_VERSION= instead of Unix shell commands.

[matthewdouglas]

Thanks, generally this looks OK. Please fix the lint issue. It may be worth it to add a note about PowerShell syntax too but that wouldn't block me from merging.

[github-actions]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[peter941221]

Fixed this.

I merged current main into the branch, corrected the ruff import ordering in bitsandbytes/cextension.py, and reran pre-commit run --all-files locally.

GitHub picked up the new head, but the workflow reruns landed in action_required before any jobs started, so this looks like the fork workflow approval gate rather than a code failure.

[matthewdouglas]

Hi,

Thanks for the contribution. After #1980 there's conflicts now, but also the need for this should be significantly reduced as well. As such I'm going to close this.