### Install uv Package Installer

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Installs the uv package installer by downloading and executing an installation script. This is a prerequisite for managing fairseq2 dependencies with uv.

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install Fairseq2 with Experimental Features

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Installs Fairseq2 with experimental features and Jupyter support using uv. This allows access to the latest advancements and interactive development with Jupyter.

```sh
# Install with Jupyter and experimental features
uv sync --extra experimental
uv run jupyter lab
```

--------------------------------

### Quick Install fairseq2 with Pip

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/index

Installs the latest stable version of fairseq2 using pip. This is the simplest way to get started with the library.

```bash
pip install fairseq2

```

--------------------------------

### Complete pyproject.toml Example for fairseq2

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

A comprehensive pyproject.toml configuration file for a fairseq2 project. It includes project metadata, main dependencies, development groups, and optional dependencies for different hardware variants (CPU, CUDA).

```toml
[project]
name = "my-fairseq2-project"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "clusterscope>=0.0.31",
    "pip>=25.2",
    "tensorboard~=2.16",
    "vllm>=0.10.0",
]

[dependency-groups]
dev = [
    "pytest~=7.3",
]
lint = [
    "mypy>=1.14.1",
    "ruff>=0.8.4",
]
data = [
    "nltk>=3.9.1",
    "pyarrow>=18.1.0",
]
doc = [
    "sphinx~=7.4.0",
    "sphinxcontrib-bibtex~=2.5.0",
    "sphinx-favicon~=1.0.1",
    "sphinx-design~=0.5.0",
    "myst-parser~=4.0.0",
    "sphinxcontrib-mermaid~=1.0.0",
    "furo==2024.8.6",
    "nbsphinx~=0.9.6",
]

[project.optional-dependencies]
cpu = [
    "torch==2.7.1+cpu",
    "torchaudio==2.7.1+cpu",
    "torchvision==0.22.1+cpu",
    "fairseq2n==0.5.*",
    "fairseq2==0.5.*",
    "vllm==0.10.1",
]
cu128 = [
    "torch==2.7.1+cu128",
    "torchaudio==2.7.1+cu128",
    "torchvision==0.22.1+cu128",
    "fairseq2n==0.5.*",
    "fairseq2==0.5.*",
    "vllm==0.10.1",
]
experimental = [
    "jupyter>=1.1.1",
    "notebook>=7.3.2",
    "torch==2.7.1+cu128",
    "torchaudio==2.7.1+cu128",
    "torchvision==0.22.1+cu128",
    "fairseq2n==0.5.*",
    "fairseq2==0.5.*",
    "vllm==0.10.1",
]
v04-cu124 = [
    "torch==2.6.0+cu124",
    "torchaudio==2.6.0+cu124",
    "torchvision==0.21.0+cu124",
    "fairseq2n==0.4.5",
    "fairseq2==0.4.5",
    "vllm==0.8.5.post1",
]

[tool.uv]
default-groups = ["dev", "lint", "data"]
conflicts = [
    [
        { extra = "cpu" },
        { extra = "cu128" },
        { extra = "experimental" },
        { extra = "v04-cu124" },
    ],
]
prerelease = "allow"

[tool.uv.sources]
torch = [
    { index = "pytorch-cpu", extra = "cpu" },
    { index = "pytorch-cu128", extra = "cu128" },
    { index = "pytorch-cu128", extra = "experimental" },
    { index = "pytorch-cu124", extra = "v04-cu124" },
]
torchaudio = [
    { index = "pytorch-cpu", extra = "cpu" },
    { index = "pytorch-cu128", extra = "cu128" },
    { index = "pytorch-cu128", extra = "experimental" },
    { index = "pytorch-cu124", extra = "v04-cu124" },
]
torchvision = [
    { index = "pytorch-cpu", extra = "cpu" },
    { index = "pytorch-cu128", extra = "cu128" },
    { index = "pytorch-cu128", extra = "experimental" },
    { index = "pytorch-cu124", extra = "v04-cu124" },
]
fairseq2n = [
    { index = "fairseq2-cpu", extra = "cpu" },
    { index = "fairseq2-cu128", extra = "cu128" },
    { index = "fairseq2-experimental", extra = "experimental" },
]
```

--------------------------------

### Install Fairseq2 with Development Tools

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Installs Fairseq2 along with development and linting tools using uv. This setup is for developers who need testing (pytest) and code quality (ruff, mypy) utilities.

```sh
# Install with development tools
uv sync --extra cu128 --group dev --group lint
```

--------------------------------

### Complete Extension Setup Example (Python)

Source: https://facebookresearch.github.io/fairseq2/stable/basics/runtime_extension

Demonstrates a comprehensive example of setting up a fairseq2 extension, including registering assets from packages or files, model families, dataset families, tokenizer families, and custom model architectures.

```python
from fairseq2.runtime.config_registry import ConfigRegistrar
from fairseq2.runtime.dependency import DependencyContainer
from fairseq2.composition import register_package_assets, register_file_assets, register_dataset_family, register_model_family, register_tokenizer_family
from my_package.models.my_custom_model import MyCustomModel, MyCustomModelConfig, create_my_custom_model

def setup_my_fairseq2_extension(container: DependencyContainer) -> None:
    # Register custom objects here...
    container.register(...)

    # Register assets (yaml files) from your package, which extends fairseq2
    register_package_assets(container, "my_package.assets")

    # Or register assets from a file path, where you put your asset yaml files
    register_file_assets(container, Path("path/to/assets"))

    # Register model families (if any)
    register_model_family(
        container,
        "my_custom_model",  # model family name
        kls=MyCustomModel,  # model class
        config_kls=MyCustomModelConfig,  # model config class
        factory=create_my_custom_model,  # factory function
        # ... other parameters
    )

    # Register dataset families (if any)
    register_dataset_family(
        container,             # DependencyContainer instance
        "custom_dataset",      # family name
        CustomDataset,         # dataset class
        CustomDatasetConfig,   # config class
        opener=custom_opener   # opener function
    )

    # Register tokenizer families (if any)
    register_tokenizer_family(
        container,
        "custom_tokenizer",     # tokenizer family name
        CustomTokenizer,        # tokenizer class
        CustomTokenizerConfig,  # tokenizer config class
        loader=custom_loader,   # loader function
    )

    # Register model architectures
    arch = ConfigRegistrar(container, MyCustomModelConfig)

    @arch("my_custom_arch_variant")  # architecture name
    def my_custom_arch_variant() -> MyCustomModelConfig:
        config = MyCustomModelConfig()
        # ... customize your config here...
        return config

```

--------------------------------

### Basic Fairseq2 Installation and Usage with uv

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/setup_with_uv

This snippet demonstrates basic installation and usage of fairseq2 using the `uv` package manager. It covers installing with CUDA or CPU, and running basic fairseq2 commands.

```bash
# Install with CUDA 12.8 (recommended for GPU users)
uv sync --extra cu128

# Install with CPU-only (for development/CI)
uv sync --extra cpu

# Run fairseq2 commands
uv run python -m fairseq2.assets list --kind model
uv run python -c "from fairseq2.models.hub import load_model; print('✓ fairseq2 works!')"

```

--------------------------------

### Fairseq2 Experimental Features with uv

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/setup_with_uv

This snippet demonstrates how to install fairseq2 with experimental features and Jupyter, and then launch Jupyter Lab.

```bash
# Install with Jupyter and experimental features
uv sync --extra experimental
uv run jupyter lab

```

--------------------------------

### Initialize Project with uv

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Initializes a new project for dependency management with uv, creating a pyproject.toml file if one does not exist. This is the first step in setting up a detailed project structure.

```sh
mkdir my-fairseq2-project
cd my-fairseq2-project
uv init
```

--------------------------------

### Install Fairseq2 from Local Source

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Installs Fairseq2 from a local source repository in editable mode, alongside the CUDA 12.8 variant. This is useful for development workflows where you are modifying the Fairseq2 codebase.

```sh
# Install fairseq2 from local source in editable mode
uv sync --extra cu128
source .venv/bin/activate
uv pip install -e /path/to/fairseq2/repo
```

--------------------------------

### Installing Fairseq2 from Local Source with uv

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/setup_with_uv

This snippet explains how to install fairseq2 from a local source repository in editable mode using `uv` and pip.

```bash
# Install fairseq2 from local source in editable mode
uv sync --extra cu128
source .venv/bin/activate
uv pip install -e /path/to/fairseq2/repo

```

--------------------------------

### Run Fairseq2 Commands

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Executes Fairseq2 commands using the uv run utility. This allows you to interact with Fairseq2 functionalities within the managed environment, such as listing models or verifying the installation.

```sh
# Run fairseq2 commands
uv run python -m fairseq2.assets list --kind model
uv run python -c "from fairseq2.models.hub import load_model; print('✓ fairseq2 works!')"
```

--------------------------------

### Install Fairseq2 with CPU-only

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Installs Fairseq2 with CPU-only support using the uv package manager. This is suitable for development, CI environments, or systems without a compatible NVIDIA GPU.

```sh
# Install with CPU-only (for development/CI)
uv sync --extra cpu
```

--------------------------------

### Fairseq2 Development Workflow with uv

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/setup_with_uv

This snippet outlines a development workflow for fairseq2 using `uv`. It includes installing with development and linting tools, and running linting and testing commands.

```bash
# Install with development tools
uv sync --extra cu128 --group dev --group lint

# Run linting
uv run ruff check .
uv run ruff format --check .
uv run mypy src/

# Run tests
uv run pytest tests/ -v

```

--------------------------------

### Switch Fairseq2 Environment to CPU for Testing

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Changes the Fairseq2 installation to the CPU-only variant and runs tests. This is useful for testing compatibility or when a GPU is not available.

```sh
# Switch to CPU for testing
uv sync --extra cpu
uv run pytest tests/
```

--------------------------------

### Quick Start: Load Qwen Model and Tokenizer

Source: https://facebookresearch.github.io/fairseq2/stable/reference/fairseq2.models.qwen

Demonstrates how to load Qwen models and their corresponding tokenizers using the fairseq2 library. It shows how to get model hubs, list available architectures, load a specific model ('qwen25_7b'), and load its tokenizer. The example also includes basic text encoding.

```python
from fairseq2.models.qwen import get_qwen_model_hub, get_qwen_tokenizer_hub

# Get the model hub
hub = get_qwen_model_hub()

# List available architectures
print("Available Qwen architectures:")
for arch in sorted(hub.get_archs()):
    print(f"  - {arch}")

# Load a model
model = hub.load_model("qwen25_7b")

# Load corresponding tokenizer
tokenizer = get_qwen_tokenizer_hub().load_tokenizer("qwen25_7b")

# Generate some text
text = "The future of AI is"
encoder = tokenizer.create_encoder()
encoded = encoder(text)
# ... model inference code ...

```

--------------------------------

### Create a Fresh Fairseq2 Environment

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Removes existing environment files and creates a new Fairseq2 installation with CUDA 12.8 support. This is a common troubleshooting step for environment issues.

```sh
# Create fresh environment
rm -rf .venv uv.lock
uv sync --extra cu128
```

--------------------------------

### Complete fairseq2 Extension Setup Example (Python)

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/basics/runtime_extension.rst

A comprehensive example demonstrating how to set up a fairseq2 extension in Python. It shows how to register assets from packages or file paths, and define custom model, dataset, tokenizer families, and model architectures.

```python
from fairseq2.runtime.config_registry import ConfigRegistrar
from fairseq2.runtime.dependency import DependencyContainer
from fairseq2.composition import register_package_assets, register_file_assets, register_dataset_family, register_model_family, register_tokenizer_family
from my_package.models.my_custom_model import MyCustomModel, MyCustomModelConfig, create_my_custom_model
from pathlib import Path

def setup_my_fairseq2_extension(container: DependencyContainer) -> None:
    # Register custom objects here...
    container.register(...)

    # Register assets (yaml files) from your package, which extends fairseq2
    register_package_assets(container, "my_package.assets")

    # Or register assets from a file path, where you put your asset yaml files
    register_file_assets(container, Path("path/to/assets"))

    # Register model families (if any)
    register_model_family(
        container,
        "my_custom_model",  # model family name
        kls=MyCustomModel,  # model class
        config_kls=MyCustomModelConfig,  # model config class
        factory=create_my_custom_model,  # factory function
        # ... other parameters
    )

    # Register dataset families (if any)
    register_dataset_family(
        container,             # DependencyContainer instance
        "custom_dataset",      # family name
        CustomDataset,         # dataset class
        CustomDatasetConfig,   # config class
        opener=custom_opener   # opener function
    )

    # Register tokenizer families (if any)
    register_tokenizer_family(
        container,
        "custom_tokenizer",     # tokenizer family name
        CustomTokenizer,        # tokenizer class
        CustomTokenizerConfig,  # tokenizer config class
        loader=custom_loader,   # loader function
    )

    # Register model architectures
    arch = ConfigRegistrar(container, MyCustomModelConfig)

    @arch("my_custom_arch_variant")  # architecture name
    def my_custom_arch_variant() -> MyCustomModelConfig:
        config = MyCustomModelConfig()
        # ... customize your config here...
        return config
```

--------------------------------

### Example End-to-End Fairseq2 Wheel Build Script

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/installation_from_source.rst

A comprehensive script demonstrating the end-to-end process of building fairseq2 wheels. It sets up a Conda environment, installs dependencies including PyTorch with specific CUDA versions, clones the repository, configures CMake with custom CUDA architectures and build options, and builds wheels for both native and Python packages.

```sh
python_version=3.10.14
torch_version=2.7.1
cuda_version=12.8
variant=cu128
arch=linux-x86_64

conda create --name fs2_build_wheel python=$python_version
conda activate fs2_build_wheel
conda install -c conda-forge libsndfile compilers=1.2.0

pip install --extra-index-url https://download.pytorch.org/whl/$variant    torch==$torch_version

git clone --recurse-submodules git@github.com:facebookresearch/fairseq2.git
cd fairseq2
pip install --requirement native/python/requirements-build.txt

version=0.5.1
tools/set-project-version.sh --native-only $version+$variant

cuda_archs="70-real;80-real;80-virtual"
cuda=ON
build_type=Release
lto=ON
sanitizers=nosan

# fairseq2/native
cd native
cmake    -GNinja    -DCMAKE_BUILD_TYPE=$build_type    -DCMAKE_CUDA_ARCHITECTURES="$cuda_archs"    -DFAIRSEQ2N_PERFORM_LTO=$lto    -DFAIRSEQ2N_SANITIZERS="${SANITIZERS/_/;}"    -DFAIRSEQ2N_TREAT_WARNINGS_AS_ERRORS=ON    -DFAIRSEQ2N_USE_CUDA=$cuda    -DFAIRSEQ2N_PYTHON_DEVEL=OFF    -B build

cmake --build build

# fairseq2/native/python
cd python
pip wheel    --use-pep517    --no-build-isolation    --no-deps    --config-settings "--build-option=--plat-name"    --config-settings "--build-option=manylinux_2_28_$arch"    --wheel-dir build/wheelhouse    .

ls build/wheelhouse/

# fairseq2/
cd ../../
pip wheel --no-deps --wheel-dir build/wheelhouse .
ls build/wheelhouse/

```

--------------------------------

### Install fairseq2 with CPU-only using uv

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Installs fairseq2 with CPU-only dependencies using the uv sync command with the --extra flag. This is suitable for environments where GPU acceleration is not available or needed.

```sh
uv sync --extra cpu
```

--------------------------------

### Verifying fairseq2 and PyTorch Installation

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/setup_with_uv

Commands to verify the successful installation of fairseq2 and PyTorch using `uv run`. It prints the versions of both libraries and checks if CUDA is available for PyTorch, helping to diagnose import errors.

```bash
# Verify installation
uv run python -c "import fairseq2; print(fairseq2.__version__)"
uv run python -c "import torch; print(f'PyTorch: {torch.__version__}, CUDA: {torch.cuda.is_available()}')"

```

--------------------------------

### Editable Development Installation of fairseq2

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/index

Sets up fairseq2 for development by cloning the repository, installing it in editable mode (`-e`), and installing development requirements. This allows for direct code modification and testing.

```bash
git clone https://github.com/facebookresearch/fairseq2.git
cd fairseq2
pip install -e . --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/pt2.8.0/cu128
pip install -r requirements-devel.txt

```

--------------------------------

### Add fairseq2 to Project with uv

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Adds the fairseq2 package to the current project's dependencies using the uv package manager. This command simplifies the process of including fairseq2 in your development environment.

```sh
uv add fairseq2
```

--------------------------------

### Run fairseq2 Commands with uv

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Executes fairseq2 commands, such as listing assets, using uv's run functionality. This ensures that the command is executed within the context of the managed environment.

```sh
uv run python -m fairseq2.assets list --kind model
```

--------------------------------

### Run Linting Tools

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Executes linting checks using ruff and mypy within the Fairseq2 development environment. These commands help maintain code quality and identify potential issues.

```sh
# Run linting
uv run ruff check .
uv run ruff format --check .
uv run mypy src/
```

--------------------------------

### Qwen Model Hub Quick Start: Load, Create, and List Models

Source: https://facebookresearch.github.io/fairseq2/stable/reference/fairseq2.models.hub

Demonstrates how to use the Qwen model hub to get available architectures, create new model instances, load models from asset cards, and load custom checkpoints. Requires fairseq2 and its dependencies.

```python
from fairseq2.models.qwen import get_qwen_model_hub
from pathlib import Path

# Get the model hub for Qwen family
hub = get_qwen_model_hub()

# List available architectures
archs = hub.get_archs()
print(f"Available architectures: {archs}")

# Create a new uninitialized model
config = hub.get_arch_config("qwen25_7b")
model = hub.create_new_model(config)

# Load a model from asset card
model = hub.load_model("qwen25_7b")

# Load a model from custom checkpoint
model = hub.load_custom_model(Path("/path/to/checkpoint.pt"), config)

```

--------------------------------

### Install Fairseq2 Python Package

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/installation_from_source.rst

Installs the fairseq2 Python package after building the native components. This involves navigating to the Python directory and using pip to install the package.

```sh
cd native/python
pip install .
cd -
```

```sh
pip install .
```

--------------------------------

### Install Fairseq2 with CUDA 12.8

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Installs Fairseq2 with CUDA 12.8 support using the uv package manager. This is the recommended installation for users with NVIDIA GPUs and CUDA 12.8 installed.

```sh
# Install with CUDA 12.8 (recommended for GPU users)
uv sync --extra cu128
```

--------------------------------

### Install Legacy Fairseq2 v0.4 with CUDA 12.4

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Installs a specific legacy version of Fairseq2 (v0.4) with CUDA 12.4 support. This is for users who need to work with older versions of the library.

```sh
# Use fairseq2 v0.4 with CUDA 12.4
uv sync --extra v04-cu124
```

--------------------------------

### Initialize a new project with uv

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/setup_with_uv

Creates a new project directory and initializes it with a pyproject.toml file using uv. This sets up the project for dependency management.

```shell
# Create new project
mkdir my-fairseq2-project
cd my-fairseq2-project

# Initialize with pyproject.toml (see configuration below)
uv init
```

--------------------------------

### Switch Fairseq2 Environment back to CUDA for Training

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Reverts the Fairseq2 installation to the CUDA 12.8 variant for tasks like model training. This command assumes a previous CUDA installation.

```sh
# Switch back to CUDA for training
uv sync --extra cu128
uv run python train_model.py
```

--------------------------------

### Check CUDA Version and Verify Installation

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Checks the system's CUDA version using nvidia-smi and verifies the Fairseq2 and PyTorch installations. This is crucial for troubleshooting CUDA-related issues and import errors.

```sh
# Check your CUDA version
nvidia-smi

# Use matching variant:
# CUDA 12.8 -> --extra cu128
# CUDA 12.4 -> --extra v04-cu124
# No GPU -> --extra cpu

# Verify installation
uv run python -c "import fairseq2; print(fairseq2.__version__)"
uv run python -c "import torch; print(f'PyTorch: {torch.__version__}, CUDA: {torch.cuda.is_available()}')"
```

--------------------------------

### Setup Training Entry Point in fairseq2

Source: https://facebookresearch.github.io/fairseq2/stable/basics/building_recipes

This Python code sets up the entry point for training in fairseq2. It initializes a custom recipe instance and passes it to the `train_main` function, which handles argument parsing, configuration loading, distributed training setup, logging, error handling, and checkpoint management.

```python
from fairseq2.recipe.cli import train_main
from .recipe import LMTrainRecipe

# Create recipe instance
recipe = LMTrainRecipe()

# Run training with automatic CLI handling
train_main(recipe)

```

--------------------------------

### Running Fairseq2 Training Recipes (Command Line)

Source: https://facebookresearch.github.io/fairseq2/stable/basics/building_recipes

Demonstrates how to execute fairseq2 training recipes from the command line. Includes examples for running with default configurations, dumping the default configuration to YAML, and overriding configuration parameters via command-line arguments.

```bash
# Run with default configuration
python -m recipes.lm.train /output/dir

# Check the default configuration (yaml format)
python -m recipes.lm.train --dump-config

# Override configuration with your own yaml file + config overrides
python -m your_package.lm.train \
    --config-file /path/to/config.yaml \
    --config model.name=llama3_2_1b_instruct regime.num_steps=20 lr_scheduler.config.num_warmup_steps=10

# Specify asset store paths
python -m your_package.lm.train \
    --config common.asset.extra_paths="['/path/to/assets/dir', '/path/to/yet_other_assets/dir']"

```

--------------------------------

### Install fairseq2 with CUDA 12.8 using uv

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Installs fairseq2 along with CUDA 12.8 specific dependencies using the uv sync command with the --extra flag. This is for projects requiring GPU acceleration with CUDA 12.8.

```sh
uv sync --extra cu128
```

--------------------------------

### Install Nightly Builds of fairseq2

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/index

Installs the latest nightly build of fairseq2 using the `--pre` flag and specifying the nightly index URL. This provides access to the most recent features and fixes.

```bash
pip install fairseq2 --pre \
  --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/nightly/pt2.8.0/cu128

```

--------------------------------

### Switching Fairseq2 Environments with uv

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/setup_with_uv

This snippet shows how to switch between different fairseq2 environments using `uv`, specifically switching to CPU for testing and back to CUDA for training.

```bash
# Switch to CPU for testing
uv sync --extra cpu
uv run pytest tests/

# Switch back to CUDA for training
uv sync --extra cu128
uv run python train_model.py

```

--------------------------------

### Install fairseq2 with Extras and Specific Git Commit

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/index

Installs fairseq2 with additional extras (like `arrow`) and from a specific commit hash in the Git repository. It also specifies PyTorch and CUDA versions via `--extra-index-url`.

```bash
pip install 'fairseq2[arrow] @ git+https://github.com/facebookresearch/fairseq2.git@<commit-hash>' \
  --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/pt2.8.0/cu128

```

--------------------------------

### Clear uv Cache and Reinstall

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Clears the uv package manager cache and performs a fresh installation of Fairseq2 with CUDA 12.8 support. This is a troubleshooting step for version mismatch errors.

```sh
# Clear uv cache and reinstall
uv cache clean
uv sync --no-cache --extra cu128
```

--------------------------------

### Clone fairseq2 Repository with Submodules

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/installation_from_source

Clones the fairseq2 Git repository and its third-party dependencies recursively. This is the initial step for installing from source.

```bash
git clone --recurse-submodules https://github.com/facebookresearch/fairseq2.git
```

--------------------------------

### Run fairseq2 Training Job (SLURM Example)

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/guides/pudb.rst

Example commands for allocating resources using SLURM and then launching a fairseq2 training job. Replace placeholders with your specific configuration and paths.

```bash
# Adjust the arguments (`--nodes`, `--ntasks-per-node`, etc.) as needed for your environment
salloc --nodes=1 --ntasks-per-node=8 --cpus-per-task=10 -t 1:00:00 --gpus-per-node=8
```

```bash
srun python -m recipes.lm.train $OUTPUT_DIR --config-file $CONFIG_YAML
```

--------------------------------

### Fairseq2 Legacy Version Installation with uv

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/setup_with_uv

This snippet shows how to install a specific legacy version of fairseq2 (v0.4) with CUDA 12.4 using `uv`.

```bash
# Use fairseq2 v0.4 with CUDA 12.4
uv sync --extra v04-cu124

```

--------------------------------

### Run fairseq2 Test Suite

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/installation_from_source

Executes the test suite to verify the correct installation of fairseq2. The tests can be run on CPU by default or on a specific device like a GPU using the --device option.

```shell
pip install -r requirements-devel.txt
pytest

```

```shell
pytest --device cuda:0

```

--------------------------------

### Checking CUDA Version and Selecting Variants

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/setup_with_uv

Instructions for checking the installed CUDA version using `nvidia-smi` and selecting the appropriate uv extra (hardware variant) for fairseq2 installation based on the CUDA version. This ensures compatibility between PyTorch, fairseq2, and the GPU.

```bash
# Check your CUDA version
nvidia-smi

# Use matching variant:
# CUDA 12.8 -> --extra cu128
# CUDA 12.4 -> --extra v04-cu124
# No GPU -> --extra cpu

```

--------------------------------

### Run Fairseq2 Test Suite

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/installation_from_source.rst

Executes the fairseq2 test suite to verify the installation. It can be run on CPU by default or on a specific device like a GPU using the --device option.

```sh
pip install -r requirements-devel.txt
pytest
```

```sh
pytest --device cuda:0
```

--------------------------------

### Load Pre-defined Models by Name

Source: https://facebookresearch.github.io/fairseq2/stable/reference/fairseq2.models.hub

Loads a model by its registered name from the asset store. This is the simplest way to get started with a known model.

```python
model = load_model("qwen25_7b")
model = load_model("llama3_8b")
model = load_model("mistral_7b")
```

--------------------------------

### Lock Fairseq2 Environment

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Generates a lock file for the Fairseq2 environment using uv. This ensures reproducible builds by pinning all dependencies to specific versions.

```sh
# Pin Your Environment: Use ``uv lock`` to create reproducible builds
uv lock
```

--------------------------------

### Initialize and Update Git Submodules

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/installation_from_source

Updates and initializes Git submodules in an existing fairseq2 repository clone. Use this if the repository was cloned without the `--recurse-submodules` flag.

```bash
git submodule update --init --recursive
```

--------------------------------

### Run Tests

Source: https://facebookresearch.github.io/fairseq2/stable/_sources/getting_started/installation/setup_with_uv.rst

Executes the test suite for Fairseq2 using pytest within the managed environment. This is part of the development workflow to ensure the code functions correctly.

```sh
# Run tests
uv run pytest tests/ -v
```

--------------------------------

### Creating a Fresh Environment with uv

Source: https://facebookresearch.github.io/fairseq2/stable/getting_started/installation/setup_with_uv

Steps to create a clean environment by removing existing virtual environment and uv lock files, then synchronizing dependencies with a specific hardware extra (e.g., CUDA 12.8). This is recommended for troubleshooting environment-specific issues.

```bash
# Create fresh environment
rm -rf .venv uv.lock
uv sync --extra cu128

```