OneTrainerをUVで動かす

概要

Stable Diffusion の LoRA モデルの学習ツールである OneTrainer を、UV環境で動作させるようにするための作業メモです。

手順

UVインストール

UV 公式の手順に沿ってインストールします。
Windows環境なので以下のコマンドで導入しました。

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv self update
uv self version

Gitインストール

Git をインストールします。git コマンドが使用できることを確認しておきます。

git --version

OneTrainerインストール

1. リポジトリクローン

任意の場所にクローンします。

git clone https://github.com/Nerogar/OneTrainer.git OneTrainer
cd OneTrainer

2. pythonバージョン指定

OneTrainer 公式によると OneTrainer requires Python >=3.10 and <3.14. とのことですので、3.13の最新を入れました。

# uv init時に失敗するので退避させておく。
mv pyproject.toml pyproject.toml.bak

uv python pin 3.13
uv init -p 3.13
uv sync

3. toml修正

退避した pyproject.toml.bak の中身を、UVが生成した pyproject.toml に移植します。
移植後の中身はこんな感じ。

[project]
name = "onetrainer"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.10"
dependencies = []

[tool.ruff]
extend-exclude = [
    # Exclude all third-party dependencies and environments.
    # NOTE: Conda installs mgds+diffusers into "src/" in the project directory.
    ".venv*",
    "venv*",
    "conda_env*",
    "src",
    # Do not lint the universal Python 2/3 version checker.
    "scripts/util/version_check.py",
]
line-length = 120

[tool.ruff.lint]
select = ["F", "E", "W", "I", "B", "UP", "YTT", "BLE", "C4", "T10", "ISC", "ICN", "PIE", "PYI", "RSE", "RET", "SIM", "PGH", "FLY", "NPY", "PERF"]
ignore = ["BLE001", "E402", "E501", "B024", "PGH003", "RET504", "RET505", "SIM102", "UP015", "PYI041"]

[tool.ruff.lint.isort.sections]
hf = ["diffusers*", "transformers*"]
mgds = ["mgds"]
torch = ["torch*"]

[tool.ruff.format]
quote-style = "double"
docstring-code-format = true

[tool.ruff.lint.isort]
known-first-party = ["modules"]
section-order = [
    "future",
    "standard-library",
    "first-party",
    "mgds",
    "torch",
    "hf",
    "third-party",
    "local-folder",
]

[!NOTE]
現在のバージョンでのtomlの話なので、適宜読み替えること。

4. requirementsインストール

インストール前に一部requirementsにて修正が必要でした。

requirements-global.txt

requirements-global.txt

# 修正箇所1
-e git+https://github.com/huggingface/diffusers.git@99daaa8#egg=diffusers
↓
diffusers @ git+https://github.com/huggingface/diffusers.git@99daaa8

# 修正箇所2
-e git+https://github.com/Nerogar/mgds.git@5bbafa5#egg=mgds
↓
mgds @ git+https://github.com/Nerogar/mgds.git@5bbafa5

# 修正箇所3
-e git+https://github.com/KellerJordan/Muon.git@f90a42b#egg=muon-optimizer
↓
muon-optimizer @ git+https://github.com/KellerJordan/Muon.git@f90a42b

修正が終わったら、以下のコマンドでインストールします。

uv pip install -r requirements.txt --index-strategy unsafe-best-match

OneTrainer実行(GUI)

UV環境でセットアップしたため、元の start-ui.bat は使用できません。
代わりに以下のバッチを用意します

start-ui-uv.bat

@echo off
chcp 65001 >nul
cd /d "%~dp0"

set HF_HUB_DISABLE_XET=1
set PYTHONUTF8=1
set PYTHONLEGACYWINDOWSSTDIO=1

uv run python -X utf8 scripts\train_ui.py

pause

OneTrainerが無事起動すれば準備完了です！

備考: OneTrainer実行(CUI)

CUIスクリプトを使用する場合は以下のコマンドで起動できます。

# コマンド例
uv run .\scripts\calculate_loss.py -h