> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/huggingface/trl/llms.txt
> Use this file to discover all available pages before exploring further.

# Script Utilities

> Argument dataclasses, parser, dataset loading, and logging helpers for TRL training scripts.

The `trl.scripts` module provides the building blocks for writing training scripts: a YAML-aware argument parser (`TrlParser`), common argument dataclasses (`ScriptArguments`, `ModelConfig`), a dataset mixture loader (`get_dataset` / `DatasetMixtureConfig`), and a logging initializer (`init_zero_verbose`).

```python theme={null}
from trl import (
    TrlParser,
    ScriptArguments,
    DatasetMixtureConfig,
    get_dataset,
    init_zero_verbose,
)
from trl.trainer import ModelConfig
```

***

## TrlParser

`TrlParser` extends `transformers.HfArgumentParser` with support for **YAML configuration files** and **environment variable injection**. Pass `--config path/to/config.yaml` on the command line to load defaults from a file; command-line arguments always override config file values.

The `env` key in the YAML file can set environment variables before the rest of the config is applied.

### Signature

```python theme={null}
class TrlParser(HfArgumentParser):
    def __init__(
        self,
        dataclass_types: DataClassType | Iterable[DataClassType] | None = None,
        **kwargs,
    )
```

### Parameters

<ParamField path="dataclass_types" type="DataClassType | Iterable[DataClassType]" optional>
  One or more dataclass types to parse arguments into. None of the dataclasses may have a field named `"config"` (reserved for the config file path).
</ParamField>

### Methods

<AccordionGroup>
  <Accordion title="parse_args_and_config">
    Parses command-line arguments and an optional YAML config file.

    ```python theme={null}
    def parse_args_and_config(
        self,
        args: Iterable[str] | None = None,
        return_remaining_strings: bool = False,
        fail_with_unknown_args: bool = True,
        separate_remaining_strings: bool = False,
    ) -> tuple[DataClass, ...]
    ```

    The config file (specified via `--config`) is loaded with `yaml.safe_load`. Its `env` section (if present) sets environment variables. All other keys are used as argument defaults. Raises `ValueError` for unknown config keys when `fail_with_unknown_args=True`.
  </Accordion>

  <Accordion title="set_defaults_with_config">
    Overrides argument defaults with values from keyword arguments (typically from a YAML config). Marks overridden arguments as no longer required.

    ```python theme={null}
    def set_defaults_with_config(self, **kwargs) -> list[str]
    ```

    Returns a list of string tokens for keys not recognized by the parser.
  </Accordion>
</AccordionGroup>

### Example

<CodeGroup>
  ```yaml config.yaml theme={null}
  env:
    TOKENIZERS_PARALLELISM: "false"
  arg1: 23
  ```

  ```python main.py theme={null}
  import os
  from dataclasses import dataclass
  from trl import TrlParser

  @dataclass
  class MyArguments:
      arg1: int
      arg2: str = "alpha"

  parser = TrlParser(dataclass_types=[MyArguments])
  (args,) = parser.parse_args_and_config()
  print(args, os.environ.get("TOKENIZERS_PARALLELISM"))
  ```

  ```bash cli theme={null}
  # Load from config file
  python main.py --config config.yaml
  # (MyArguments(arg1=23, arg2='alpha'),) false

  # Override config values on the CLI
  python main.py --config config.yaml --arg2 beta
  # (MyArguments(arg1=23, arg2='beta'),) false
  ```
</CodeGroup>

***

## ScriptArguments

A dataclass holding dataset-related arguments common to all TRL training scripts. Designed to be used with `TrlParser`.

### Signature

```python theme={null}
@dataclass
class ScriptArguments:
    dataset_name: str | None = None
    dataset_config: str | None = None
    dataset_train_split: str = "train"
    dataset_test_split: str = "test"
    dataset_streaming: bool = False
    ignore_bias_buffers: bool = False
```

### Fields

<ParamField path="dataset_name" type="str" optional>
  Path or name of the dataset to load via `datasets.load_dataset`. Ignored when `DatasetMixtureConfig.datasets` is provided.
</ParamField>

<ParamField path="dataset_config" type="str" optional>
  Dataset configuration name, corresponding to the `name` argument of `datasets.load_dataset`. Ignored when a mixture config is used.
</ParamField>

<ParamField path="dataset_train_split" type="str" default="'train'">
  Dataset split to use for training.
</ParamField>

<ParamField path="dataset_test_split" type="str" default="'test'">
  Dataset split to use for evaluation.
</ParamField>

<ParamField path="dataset_streaming" type="bool" default="False">
  When `True`, loads the dataset in streaming mode.
</ParamField>

<ParamField path="ignore_bias_buffers" type="bool" default="False">
  Debug flag for distributed training. Fixes DDP issues with LM bias/mask buffers.
</ParamField>

### Example

```python theme={null}
from trl import TrlParser, ScriptArguments

parser = TrlParser(dataclass_types=[ScriptArguments])
(args,) = parser.parse_args_and_config()
print(args.dataset_name)
```

***

## ModelConfig

A dataclass holding model loading and PEFT configuration, designed for use with `TrlParser`.

### Signature

```python theme={null}
@dataclass
class ModelConfig:
    model_name_or_path: str | None = None
    model_revision: str = "main"
    dtype: str | None = "float32"
    trust_remote_code: bool = False
    attn_implementation: str | None = None
    use_peft: bool = False
    lora_r: int = 16
    lora_alpha: int = 32
    lora_dropout: float = 0.05
    lora_target_modules: list[str] | None = None
    lora_target_parameters: list[str] | None = None
    lora_modules_to_save: list[str] | None = None
    lora_task_type: str = "CAUSAL_LM"
    use_rslora: bool = False
    use_dora: bool = False
    load_in_8bit: bool = False
    load_in_4bit: bool = False
    bnb_4bit_quant_type: str = "nf4"
    use_bnb_nested_quant: bool = False
    bnb_4bit_quant_storage: str | None = None
```

### Key fields

<AccordionGroup>
  <Accordion title="Model loading">
    <ParamField path="model_name_or_path" type="str" optional>
      HuggingFace Hub identifier or local path of the model checkpoint.
    </ParamField>

    <ParamField path="model_revision" type="str" default="'main'">
      Branch name, tag, or commit hash to load.
    </ParamField>

    <ParamField path="dtype" type="str" default="'float32'">
      Load dtype override. One of `"auto"`, `"bfloat16"`, `"float16"`, `"float32"`.
    </ParamField>

    <ParamField path="trust_remote_code" type="bool" default="False">
      Allow execution of custom model code from the Hub. Only enable for repositories you trust.
    </ParamField>

    <ParamField path="attn_implementation" type="str" optional>
      Attention kernel to use (e.g., `"flash_attention_2"`).
    </ParamField>
  </Accordion>

  <Accordion title="PEFT / LoRA">
    <ParamField path="use_peft" type="bool" default="False">
      Enable PEFT/LoRA fine-tuning.
    </ParamField>

    <ParamField path="lora_r" type="int" default="16">
      LoRA rank.
    </ParamField>

    <ParamField path="lora_alpha" type="int" default="32">
      LoRA scaling factor.
    </ParamField>

    <ParamField path="lora_dropout" type="float" default="0.05">
      LoRA dropout probability.
    </ParamField>

    <ParamField path="lora_target_modules" type="list[str]" optional>
      Module names to apply LoRA to.
    </ParamField>

    <ParamField path="lora_task_type" type="str" default="'CAUSAL_LM'">
      PEFT task type. Use `"SEQ_CLS"` for reward modeling.
    </ParamField>

    <ParamField path="use_rslora" type="bool" default="False">
      Use Rank-Stabilized LoRA (scales adapter by `lora_alpha/√r` instead of `lora_alpha/r`).
    </ParamField>

    <ParamField path="use_dora" type="bool" default="False">
      Enable Weight-Decomposed Low-Rank Adaptation (DoRA).
    </ParamField>
  </Accordion>

  <Accordion title="Quantization">
    <ParamField path="load_in_8bit" type="bool" default="False">
      Load in 8-bit precision (requires LoRA).
    </ParamField>

    <ParamField path="load_in_4bit" type="bool" default="False">
      Load in 4-bit precision (requires LoRA).
    </ParamField>

    <ParamField path="bnb_4bit_quant_type" type="str" default="'nf4'">
      4-bit quantization type: `"fp4"` or `"nf4"`.
    </ParamField>

    <ParamField path="use_bnb_nested_quant" type="bool" default="False">
      Enable nested quantization (double quantization).
    </ParamField>
  </Accordion>
</AccordionGroup>

### Example

```python theme={null}
from trl import TrlParser, ScriptArguments
from trl.trainer import ModelConfig

parser = TrlParser(dataclass_types=[ScriptArguments, ModelConfig])
(script_args, model_config) = parser.parse_args_and_config()

from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained(
    model_config.model_name_or_path,
    torch_dtype=model_config.dtype,
    trust_remote_code=model_config.trust_remote_code,
)
```

***

## DatasetMixtureConfig

Configuration dataclass for loading and combining multiple datasets into a single training mixture. Each dataset in the mixture is described by a `DatasetConfig` entry.

### Signature

```python theme={null}
@dataclass
class DatasetMixtureConfig:
    datasets: list[DatasetConfig] = field(default_factory=list)
    streaming: bool = False
    test_split_size: float | None = None
```

### Fields

<ParamField path="datasets" type="list[DatasetConfig]">
  List of individual dataset configurations. Each entry specifies a `path`, optional `name`, `data_dir`, `data_files`, `split`, and `columns`.
</ParamField>

<ParamField path="streaming" type="bool" default="False">
  Load all datasets in streaming mode.
</ParamField>

<ParamField path="test_split_size" type="float" optional>
  If provided, the combined dataset is split into `train` and `test` subsets using this fraction as the test size.
</ParamField>

### YAML usage

```yaml theme={null}
datasets:
  - path: trl-lib/tldr
    split: train
  - path: trl-lib/ultrafeedback_binarized
    split: train
streaming: false
test_split_size: 0.05
```

***

## get\_dataset

Loads and concatenates a mixture of datasets described by a `DatasetMixtureConfig`. Returns a `DatasetDict` with a `"train"` key (and optionally a `"test"` key when `test_split_size` is set).

### Signature

```python theme={null}
def get_dataset(mixture_config: DatasetMixtureConfig) -> DatasetDict
```

### Parameters

<ParamField path="mixture_config" type="DatasetMixtureConfig">
  Configuration specifying datasets, streaming, and optional test split.
</ParamField>

### Returns

`datasets.DatasetDict` — Combined dataset. Always contains a `"train"` split; also contains a `"test"` split if `mixture_config.test_split_size` is not `None`.

### Example

```python theme={null}
from trl import DatasetMixtureConfig, get_dataset
from trl.scripts.utils import DatasetConfig

mixture_config = DatasetMixtureConfig(
    datasets=[DatasetConfig(path="trl-lib/tldr")]
)
dataset = get_dataset(mixture_config)
print(dataset)
# DatasetDict({
#     train: Dataset({features: ['prompt', 'completion'], num_rows: 116722})
# })
```

***

## init\_zero\_verbose

Configures Python's `logging` and `warnings` for minimal, clean output — suitable for the top of CLI training scripts. Uses `RichHandler` when the `rich` package is available, falling back to a standard `StreamHandler`.

### Signature

```python theme={null}
def init_zero_verbose() -> None
```

Sets the root log level to `ERROR` and redirects `warnings.showwarning` to the logging system.

### Example

```python theme={null}
from trl import init_zero_verbose

init_zero_verbose()  # call before any other imports

from transformers import AutoModelForCausalLM
# ...
```