separate out flash-attn install (sadly)

docs/installation.qmd

@@ -31,27 +31,36 @@ For Blackwell GPUs, please use Pytorch 2.7.0 and CUDA 12.8.
 
 ### uv Installation (Recommended) {#sec-uv-quick}
 
-For a quick installation with uv:
-
 ```{.bash}
 # Install uv if not already installed
 curl -LsSf https://astral.sh/uv/install.sh | sh
 
-# Install axolotl
-uv pip install --no-build-isolation axolotl
+# Add Axolotl to a project (recommended)
+uv init my-project && cd my-project
+uv add axolotl
+uv pip install flash-attn --no-build-isolation
+source .venv/bin/activate
 ```
 
-### PyPI Installation {#sec-pypi}
+For a quick one-off install without creating a project:
 
 ```{.bash}
-pip3 install -U packaging setuptools wheel ninja
-pip3 install --no-build-isolation axolotl[flash-attn,deepspeed]
+uv pip install axolotl
+uv pip install flash-attn --no-build-isolation
+```
+
+### pip Installation {#sec-pypi}
+
+```{.bash}
+pip install --no-build-isolation axolotl[deepspeed]
+pip install --no-build-isolation flash-attn
 ```
 
 We use `--no-build-isolation` in order to detect the installed PyTorch version (if
 installed) in order not to clobber it, and so that we set the correct version of
 dependencies that are specific to the PyTorch version or other installed
-co-dependencies.
+co-dependencies. Flash Attention is resolved separately so it can be built against
+the environment configured by the previous step.
 
 ### Advanced uv Installation {#sec-uv}
 
@@ -74,17 +83,17 @@ source .venv/bin/activate
 Install PyTorch
 - PyTorch 2.6.0 recommended
 ```{.bash}
-uv pip install packaging setuptools wheel
 uv pip install torch==2.6.0
 uv pip install awscli pydantic
 ```
 
 Install axolotl from PyPi
 ```{.bash}
-uv pip install --no-build-isolation axolotl[deepspeed,flash-attn]
-
+uv pip install --no-build-isolation axolotl[deepspeed]
 # optionally install with vLLM if you're using torch==2.6.0 and want to train w/ GRPO
-uv pip install --no-build-isolation axolotl[deepspeed,flash-attn,vllm]
+# uv pip install --no-build-isolation axolotl[deepspeed,vllm]
+
+uv pip install flash-attn --no-build-isolation
 ```
 
 ### Edge/Development Build {#sec-edge-build}
@@ -97,14 +106,15 @@ git clone https://github.com/axolotl-ai-cloud/axolotl.git
 cd axolotl
 curl -LsSf https://astral.sh/uv/install.sh | sh  # If not already installed
 uv sync
+uv pip install flash-attn --no-build-isolation
 ```
 
 #### Using pip
 ```{.bash}
 git clone https://github.com/axolotl-ai-cloud/axolotl.git
 cd axolotl
-pip3 install -U packaging setuptools wheel ninja
-pip3 install --no-build-isolation -e '.[flash-attn,deepspeed]'
+pip install --no-build-isolation -e '.[deepspeed]'
+pip install --no-build-isolation flash-attn
 ```
 
 ### Docker {#sec-docker}
@@ -162,7 +172,7 @@ For providers supporting Docker:
 ### macOS {#sec-macos}
 
 ```{.bash}
-pip3 install --no-build-isolation -e '.'
+uv pip install --no-build-isolation -e '.'
 ```
 
 See @sec-troubleshooting for Mac-specific issues.
@@ -180,10 +190,15 @@ We recommend using WSL2 (Windows Subsystem for Linux) or Docker.
 1. Install Python ≥3.11
 2. Install PyTorch: https://pytorch.org/get-started/locally/
 3. Install Axolotl:
-   ```{.bash}
-   pip3 install -U packaging setuptools wheel ninja
-   pip3 install --no-build-isolation -e '.[flash-attn,deepspeed]'
-   ```
+```{.bash}
+# Option A: add Axolotl to the environment
+uv add axolotl
+uv pip install flash-attn --no-build-isolation
+
+# Option B: quick install
+uv pip install axolotl
+uv pip install flash-attn --no-build-isolation
+```
 4. (Optional) Login to Hugging Face:
    ```{.bash}
    huggingface-cli login