Skip to content

SimpleTuner v2.1 to v2.2 Migration Guide

This guide helps you migrate from SimpleTuner v2.1 to v2.2, which introduces a new command-line interface which is a one-stop entry-point for your configuration management running training jobs.

What's New in v2.2

  • pip-installable package: SimpleTuner can now be installed as a Python package
  • Unified CLI entry point: simpletuner command replaces direct script execution
  • simpletuner examples - lists example configs and allows copying to a workspace
  • simpletuner configure - interactively create or modify a fully custom config files through a terminal UI, paralleling the Linux kernel's make menuconfig
  • simpletuner train - runs training with config and CLI overrides
  • Command-line argument overrides: Pass arguments directly without editing config files for quick changes, eg. simpletuner train env=foo learning_rate=5e-5

What Remains Compatible

  • Existing train.sh workflow continues to work
  • Don't forget to cd into the new simpletuner/ subdirectory first.
  • Config file formats and contents (JSON, TOML, ENV) unchanged
  • Dataset configurations remain the same
  • Model training parameters unchanged
  • Model implementations are identical

Installation Methods

v2.2 (Pip Install Method) - Modern recommendation

Now that pip installation is supported, the recommended method is to simply install SimpleTuner as a package in a new workspace. This allows for cleaner separation of your training projects from the SimpleTuner codebase, and enables easy updates via pip install --upgrade simpletuner.

# Install SimpleTuner package
pip install 'simpletuner[cuda]' # or cuda13 (Blackwell/B-series), apple, rocm (or nothing, for CPU)

# Create training workspace
mkdir my_training_project
cd my_training_project

# Initialize config structure
mkdir -p config/sdxl_example_project

# Interactively create a configuration
simpletuner configure config/sdxl_example_project/config.json
## OR - copy an example
# simpletuner examples list # list available examples to select from
# simpletuner examples copy sdxl.lycoris-lokr config/sdxl_example_project
## Be sure to update the paths and parameters in the copied config file!

# Run training
simpletuner env=sdxl_example_project

Via Git Clone (legacy method)

In the prior release, the recommended installation method was to clone the repository and run training scripts directly. This was the only supported method, and had several drawbacks. However, this workflow remains fully supported in v2.2 for backward compatibility.

NOTE: poetry is no longer used.

# Clone repository
git clone --branch=release https://github.com/bghira/SimpleTuner.git
cd SimpleTuner

# Install dependencies with Pip now instead of Poetry
pip install '.[cuda]'  # or .[apple], or .[rocm]

# Run training - this still works, and will for the foreseeable future.
ENV=my_config train.sh
## Or, use the train.py script directly, which might not be supported forever:
#python train.py --model_family=flux --learning_rate=1e-4

Command-Line Interface Migration

Configuration Loading

v2.1 Workflow

# Set environment variable
export ENV=my_config

# Config loaded from: config/my_config/config.json
train.sh

# Or inline
ENV=my_config train.sh

v2.2 Workflow

Option 1: Environment-based Config (Backward Compatible)

# Using environment variable (same as v2.1)
ENV=my_config train.sh
# Or with new CLI
simpletuner train env=my_config

Option 2: Mixed Approach

# Load base config and override specific parameters
simpletuner train env=my_config learning_rate=5e-5 num_train_epochs=50

Configuration Management

Directory Structure

v2.1 Git Repo Structure

SimpleTuner/
├── config/
│   ├── config.json          # Default config
│   ├── my_config/
│   │   ├── config.json      # Custom config
│   │   └── config.env
│   └── another_config/
│       └── config.toml
├── train.sh
└── train.py

v2.2 Workspace Structure (Pip Install)

my_training_project/         # Your workspace (not a git repo, but it could be committed if desired for version control)
├── config/
│   ├── config.json          # Default config
│   ├── config.env           # Fallback when no env specified
│   ├── my_config/
│   │   └── config.json      # Custom config
│   └── another_config/
│       └── config.toml
├── cache/                   # VAE/text encoder caches
├── output/                  # Training outputs
└── datasets/               # Your training data

Config Loading Priority

v2.1

  1. Check ENV environment variable
  2. Load config/${ENV}/config.{json,toml,env}
  3. Fall back to config/config.{json,toml,env}

v2.2

  1. Command-line arguments (highest priority)
  2. Check SIMPLETUNER_ENV or ENV variable
  3. Load config from current directory or config subdirectory
  4. Use config.env if no environment specified
  5. Apply CLI argument overrides

Environment Variables

v2.2 supports multiple environment variable names for compatibility:

# All of these work in v2.2:
SIMPLETUNER_ENV=my_config bash train.sh
SIMPLETUNER_ENVIRONMENT=my_config bash train.sh
ENV=my_config bash train.sh  # v2.1 compatible

# Config backend selection
SIMPLETUNER_CONFIG_BACKEND=json  # or toml, env
CONFIG_BACKEND=json               # v2.1 compatible
CONFIG_TYPE=json                  # legacy support

Migrating from Git to Workspace

To migrate an existing v2.1 git repository config setup to a v2.2 pip-based workspace:

# 1. Your existing SimpleTuner clone
cd /path/to/SimpleTuner

# 2. Create new workspace
mkdir ~/training_workspace

# 3. Copy configurations - we'll assume you have subfolder based config envs.
cp -r config/* ~/training_workspace/config/

# 4. Update paths in dataloader config cache locations

# 5. Relocate, link, or update paths to datasets

# 6. Set up python environment in workspace
cd ~/training_workspace
python3.13 -m venv .venv # Create a new venv for this workspace if desired
pip install simpletuner  # Install the new v2.2 package

# 7. Remove old SimpleTuner installation if desired
# rm -rf /path/to/SimpleTuner

# 8. Run training from workspace
simpletuner train env=my_config learning_rate=5e-5

Multi-GPU Training

The same methods used to configure multi-gpu training in v2.1 still apply in v2.2:

# Accelerate config (recommended)
accelerate config  # Run once to set up, following interactive menu

# Set in config.env which will be read by the simpletuner command-line tool
echo "export TRAINING_NUM_PROCESSES=4" >> ~/my_workspace/config/config.env

Running quick experiments

v2.1: Required creating new config directories for each experiment and updating the config paths and values individually

v2.2: Run experiments with different parameters instantly:

simpletuner train learning_rate=1e-4 batch_size=1 tracker_run_name="training experiment 1"
simpletuner train learning_rate=5e-5 batch_size=2 tracker_run_name="training experiment 2"
simpletuner train learning_rate=1e-5 batch_size=4 tracker_run_name="training experiment 3"

Common Issues and Solutions

Issue 1: Config Not Found

Problem: simpletuner env=my_config can't find configuration Solution: Ensure config exists at config/my_config/config.json in current directory

Issue 2: Path Resolution

Problem: Absolute paths in config files break after migration Solution: Update to relative paths from workspace root

Issue 3: Environment Variables

Problem: Old ENV variable not working Solution: Ensure paths are correct and that the files can be found

Issue 4: Missing CLI Command

Problem: simpletuner command not found Solution: Enable virtualenv and reattempt, or reinstall SimpleTuner via pip