Axolotl

0.16.1 verified Fri May 01 auth: no python

A user-friendly LLM training framework supporting a wide range of models, including Llama, Mistral, and others. Axolotl streamlines fine-tuning with PEFT, FSDP, and other optimizations, currently at version 0.16.1. Release cadence is regular, with multiple releases per month.

pip install axolotl

Common errors

error TypeError: train() got an unexpected keyword argument 'model' ↓

cause Using old API where train was called with direct arguments instead of a config object.

fix

Use load_config to load config from YAML and pass config object: train(cfg=config).

error ImportError: cannot import name 'train' from 'axolotl' ↓

cause train() is no longer in the top-level module; moved to utils.trainer.

fix

Use: from axolotl.utils.trainer import train

error RuntimeError: CUDA out of memory ↓

cause Model too large for available GPU memory, or not using memory optimizations.

fix

Enable gradient checkpointing, use smaller batch size, or activate DeepSpeed ZeRO stage 2/3.

error KeyError: 'model_name_or_path' in config ↓

cause Required config key missing from YAML.

fix

Add 'model_name_or_path' to the YAML config file with the model identifier.

Warnings

breaking Version 0.4.0 changed the trainer API: train() now requires a config object, not kwargs. ↓

fix Use load_config to load a YAML or dict config, then call train(cfg=config).

gotcha Flash Attention must be installed separately and CUDA-compatible GPU required. ↓

fix Install with pip install axolotl[flash-attn] and ensure GPU is available.

gotcha YAML config keys are case-sensitive and must match exactly with axolotl's schema. ↓

fix Refer to the official config documentation for correct key names.

deprecated The cli.py entry point is deprecated; use the Python API or `axolotl` command-line tool. ↓

fix Use `python -m axolotl.cli.train config.yml` or the Python API.

Install

pip install axolotl[flash-attn]

pip install axolotl[deepspeed]

Imports

train
wrong
```
from axolotl import train
```
correct
```
from axolotl.utils.trainer import train
```
train() is no longer top-level; moved to utils.trainer

load_config

wrong

from axolotl.config import load_config

correct

from axolotl.utils.config import load_config

Config utilities moved under utils

Quickstart

Basic training using a YAML config file.

from axolotl.utils.config import load_config
from axolotl.utils.trainer import train

config = load_config('config.yml')
# config must include 'model_name_or_path' and other required fields
train(cfg=config)