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

LlamaFactory’s configuration system centers on src/llamafactory/hparams/parser.py for CLI argument parsing, 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 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.

# 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 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 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.

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 implements the persistence layer through two primary functions:

• load_config() – Reads the default 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.

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 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.

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 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 provides a complete LoRA SFT configuration that you can copy and modify. These files follow the exact dictionary structure produced by arg_utils.py, ensuring compatibility with both the CLI and Web UI.

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 calls the parser in hparams/parser.py to ingest CLI flags and YAML files.
2. Conversion – v1/config/arg_utils.py transforms the namespace into a nested dictionary.
3. Persistence – If using the Web UI, webui/common.py saves the dictionary to config.json or a YAML file via save_config().
4. Enumeration – 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, which instantiates TrainingArguments and launches the trainer.

Summary

• src/llamafactory/hparams/parser.py defines all CLI flags and maps them to Pydantic models like FinetuningArguments.
• src/llamafactory/v1/config/arg_utils.py converts parsed arguments into hierarchical dictionaries for YAML compatibility.
• src/llamafactory/webui/common.py provides load_config() and save_config() for reading and writing configuration files.
• 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 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 in the project root) using the save_config() function in 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, ensuring they work seamlessly with both the --config_file CLI option and the Web UI dropdown populated by control.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}