# Key Files for Configuring LlamaFactory: CLI, YAML, and Web UI Reference

> Master LlamaFactory configuration with this guide. Discover key files for CLI, YAML, and Web UI setup, including parser.py and common.py. Optimize your LlamaFactory projects today.

- Repository: [Yaowei Zheng/LlamaFactory](https://github.com/hiyouga/LlamaFactory)
- Tags: reference
- Published: 2026-03-04

---

**LlamaFactory’s configuration system centers on [`src/llamafactory/hparams/parser.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/hparams/parser.py) for CLI argument parsing, [`src/llamafactory/webui/common.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/webui/common.py) for saving and loading settings, and the `examples/` directory for reusable YAML templates.**

Configuring LlamaFactory—the open-source framework for fine-tuning large language models—requires navigating a layered system that bridges command-line flags, Python data classes, and persistent YAML files. The repository organizes these concerns into specific modules that handle everything from parsing `--model_name_or_path` to populating the Web UI’s config dropdown. Understanding these key files ensures you can modify training parameters, switch between LoRA and full fine-tuning, or automate jobs without triggering validation errors.

## Command-Line Argument Parsing

All **CLI arguments** are defined in a single location before being mapped to internal data structures.

### The Parser Module

[`src/llamafactory/hparams/parser.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/hparams/parser.py) contains the central `ArgumentParser` definition that declares every supported flag, including `--output_dir`, `--max_steps`, and `--learning_rate`. This file maps parsed arguments to Pydantic `BaseModel` subclasses such as `FinetuningArguments`, `ModelArguments`, and `TrainingArguments`. When you invoke `python -m llamafactory.train`, this module processes the command line and returns a validated namespace.

```python

# Conceptual flow inside parser.py

args = parse_args()  # Returns argparse.Namespace

# Maps to FinetuningArguments, ModelArguments, etc.

```

### Entry Point Integration

The file [`src/llamafactory/train.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/train.py) serves as the primary entry point that invokes the parser. It passes the resulting namespace downstream to the tuner logic, ensuring that flags provided at the command line override any defaults stored in YAML files.

## Configuration Conversion and Persistence

Once arguments are parsed, they must be converted to dictionaries for YAML serialization and persisted for the Web UI.

### Argument-to-Dictionary Conversion

[`src/llamafactory/v1/config/arg_utils.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/v1/config/arg_utils.py) handles the transformation of the `argparse.Namespace` object into a hierarchical dictionary suitable for YAML storage. The function `get_plugin_config()` (and related helpers) walks the namespace, strips the `--` prefix from flags, and nests keys to match the structure used by the Gradio interface.

```python
from llamafactory.v1.config.arg_utils import get_plugin_config

# Converts Namespace to nested dict for YAML compatibility

config_dict = get_plugin_config(args)

```

### Saving and Loading Configurations

[`src/llamafactory/webui/common.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/webui/common.py) implements the persistence layer through two primary functions:

- `load_config()` – Reads the default [`config.json`](https://github.com/hiyouga/LlamaFactory/blob/main/config.json) (or a user-specified YAML) from disk and returns a Python dictionary.
- `save_config()` – Writes a dictionary back to disk, enabling the Web UI to store user edits between sessions.

```python
from llamafactory.webui.common import load_config, save_config

# Load existing configuration

cfg = load_config()
print(cfg["model_name_or_path"])  # e.g., "meta-llama/Meta-Llama-3-8B"

# Persist modifications

new_cfg = {"output_dir": "./new_output", "learning_rate": 2e-4}
save_config(new_cfg)

```

This module also provides `_get_config_path()`, which resolves the location of the configuration file in the project root or a custom location.

## Web UI Configuration Management

The Gradio-based interface relies on specific utilities to enumerate and select configuration files.

### Template Enumeration

[`src/llamafactory/webui/control.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/webui/control.py) contains `list_config_paths()`, which scans the repository for available YAML templates. This function populates the “Config file” dropdown in the Web UI, allowing users to select predefined recipes such as LoRA supervised fine-tuning or DPO training.

```python
from llamafactory.webui.control import list_config_paths

paths = list_config_paths(current_time="2024-01-01")
print(paths)  # ['examples/v1/train_lora/train_lora_sft.yaml', ...]

```

### UI State Synchronization

When you adjust sliders or text boxes in the Web UI, [`webui/common.py`](https://github.com/hiyouga/LlamaFactory/blob/main/webui/common.py) ensures those changes are written back to the config file via `save_config()`. When you reload the page, `load_config()` restores the previous state, creating a seamless editing experience.

## YAML Templates and Environment Defaults

Beyond Python modules, LlamaFactory distributes ready-made configuration files and supports environment-level overrides.

### Example Configuration Files

The `examples/` directory contains hierarchical YAML templates that demonstrate best practices for different training paradigms. For instance, [`examples/v1/train_lora/train_lora_sft.yaml`](https://github.com/hiyouga/LlamaFactory/blob/main/examples/v1/train_lora/train_lora_sft.yaml) provides a complete LoRA SFT configuration that you can copy and modify. These files follow the exact dictionary structure produced by [`arg_utils.py`](https://github.com/hiyouga/LlamaFactory/blob/main/arg_utils.py), ensuring compatibility with both the CLI and Web UI.

```bash
python -m llamafactory.train \
    --config_file examples/v1/train_lora/train_lora_sft.yaml \
    --output_dir ./output \
    --max_steps 5000

```

The parser merges CLI flags with the YAML content, with command-line values taking precedence.

### Environment Variables

The optional `.env.local` file (auto-generated at first run) stores environment defaults such as `HF_HOME` or `CUDA_VISIBLE_DEVICES`. While not a core configuration file, it influences path resolution and hardware detection before the Python argument parser executes.

## End-to-End Configuration Workflow

Understanding how these files interact clarifies the complete data flow:

1. **Invocation** – [`src/llamafactory/train.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/train.py) calls the parser in [`hparams/parser.py`](https://github.com/hiyouga/LlamaFactory/blob/main/hparams/parser.py) to ingest CLI flags and YAML files.
2. **Conversion** – [`v1/config/arg_utils.py`](https://github.com/hiyouga/LlamaFactory/blob/main/v1/config/arg_utils.py) transforms the namespace into a nested dictionary.
3. **Persistence** – If using the Web UI, [`webui/common.py`](https://github.com/hiyouga/LlamaFactory/blob/main/webui/common.py) saves the dictionary to [`config.json`](https://github.com/hiyouga/LlamaFactory/blob/main/config.json) or a YAML file via `save_config()`.
4. **Enumeration** – [`webui/control.py`](https://github.com/hiyouga/LlamaFactory/blob/main/webui/control.py) lists available templates through `list_config_paths()` for UI selection.
5. **Execution** – The final merged dictionary is passed to [`src/llamafactory/train/tuner.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/train/tuner.py), which instantiates `TrainingArguments` and launches the trainer.

## Summary

- **[`src/llamafactory/hparams/parser.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/hparams/parser.py)** defines all CLI flags and maps them to Pydantic models like `FinetuningArguments`.
- **[`src/llamafactory/v1/config/arg_utils.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/v1/config/arg_utils.py)** converts parsed arguments into hierarchical dictionaries for YAML compatibility.
- **[`src/llamafactory/webui/common.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/webui/common.py)** provides `load_config()` and `save_config()` for reading and writing configuration files.
- **[`src/llamafactory/webui/control.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/webui/control.py)** implements `list_config_paths()` to populate the Web UI’s template selector.
- **`examples/**/*.yaml`** offers reusable templates for LoRA, full fine-tuning, and inference workflows.
- **`.env.local`** holds optional environment overrides that affect path resolution.

## Frequently Asked Questions

### How do I override a YAML configuration value from the command line?

Provide the flag explicitly when calling the training module. The parser in [`src/llamafactory/hparams/parser.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/hparams/parser.py) merges CLI arguments with the YAML file loaded via `--config_file`, with command-line values taking precedence. For example, appending `--max_steps 5000` overrides the step count defined in the YAML template.

### Where does LlamaFactory store Web UI settings between sessions?

The Web UI saves your configuration to a JSON file (typically [`config.json`](https://github.com/hiyouga/LlamaFactory/blob/main/config.json) in the project root) using the `save_config()` function in [`src/llamafactory/webui/common.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/webui/common.py). When you relaunch the interface, `load_config()` reads this file and restores your previous parameters, including model paths, learning rates, and LoRA rank settings.

### Can I load a configuration programmatically without using the CLI?

Yes. Import `load_config()` from `llamafactory.webui.common` to read the default configuration into a dictionary. This allows you to inspect or modify settings dynamically before passing them to the training loop, bypassing the command-line interface entirely.

### What is the purpose of the `examples/` directory YAML files?

These files serve as canonical templates that demonstrate valid parameter combinations for different tasks (e.g., LoRA SFT, DPO, reward modeling). They match the dictionary structure generated by [`arg_utils.py`](https://github.com/hiyouga/LlamaFactory/blob/main/arg_utils.py), ensuring they work seamlessly with both the `--config_file` CLI option and the Web UI dropdown populated by [`control.py`](https://github.com/hiyouga/LlamaFactory/blob/main/control.py).