docs: remove misleading FLASH_ATTENTION_SKIP_CUDA_BUILD recommendation

[like955]

Summary

Description:

This PR updates the flash-attn installation guide to prevent users from accidentally creating broken environments.

The Problem:
The documentation previously recommended setting FLASH_ATTENTION_SKIP_CUDA_BUILD = "TRUE" to "ensure" a wheel installation. However, based on an analysis of flash-attn's setup.py:

1. It is redundant: The setup script (CachedWheelsCommand) automatically prefers downloading wheels before attempting any compilation, even without this variable.
2. It is dangerous: If uv resolves to a version combination (e.g., latest Torch) for which no official wheel exists, setting this variable causes setup.py to silently skip CUDA compilation and successfully install a "hollow" package containing only Python files. This leads to confusing ImportError: No module named 'flash_attn_2_cuda' errors at runtime.

Changes:

• Removed [tool.uv.extra-build-variables] from the example pyproject.toml.
• Replaced the note with a warning about the risks of silent failures.
• Emphasized explicit version pinning as the correct way to ensure wheel compatibility.

Related Issue:
Fixes #17794

[charliermarsh]

I don’t think this is correct. I believe you need to set this if you’re on a system that does not have a GPU; otherwise, it includes the CUDAExtension and PyTorch will raise an error. I would have to test it though.

[like955]

@charliermarsh

Thank you for the feedback. I understand your concern about systems without a GPU.

You're right that setting FLASH_ATTENTION_SKIP_CUDA_BUILD="TRUE" could be necessary for installation on a GPU-less system to avoid CUDAExtension errors. My PR was primarily addressing the opposite scenario:

The Core Problem: On systems with a GPU, if a compatible pre-built wheel isn't available (e.g., due to a newer PyTorch version), setting this variable causes setup.py to skip compilation silently. This results in a "hollow" installation (only Python files) that fails at runtime with ImportError: No module named 'flash_attn_2_cuda'. The current documentation doesn't warn about this risk.

My Question:
I'm curious about the practical use case for installing flash-attn on a system without a GPU. Could you help me understand the typical scenarios? For example:

• Is it for inference on CPU-only machines?
• Or for development/testing without GPU access?

If this is a required use case, perhaps we need a more nuanced approach in the docs:

1. Keep the variable for GPU-less installs, but add a strong warning about the silent-failure risk when a GPU is present.
2. Or provide separate instructions: "Set this variable only if you have no GPU. If you have a GPU, avoid it to ensure compilation falls back when wheels are missing."

I'm happy to adjust the PR based on your guidance. If the no-GPU install path is essential, we could update the warning to be more explicit about when to use the variable, rather than removing it entirely.

[charliermarsh]

We shipped a separate update (#18473).