Large-scale refactoring has been merged into main — migration guide inside

[kohya-ss]

Update (2026-06-12): The refactoring has been merged into main via #2372. See the migration guide at the bottom of this post. If anything broke for you after updating, please reply here.

更新 (2026-06-12): リファクタリングは #2372 により main にマージされました。本投稿末尾の移行ガイドをご確認ください。更新後に動作がおかしい点があれば、このスレッドで返信をお願いします。

---

Thank you for using and contributing to this repository.

A large-scale internal refactoring is currently in progress and is nearing completion. We plan to merge it into main soon.

The user-facing interface of each script (script names, command-line options, dataset configuration, etc.) is essentially unchanged, so you can continue using the scripts as before.

On the implementation side, the architecture-specific classes are largely preserved, but the internal APIs (base classes, utility modules, etc.) have changed significantly. Maintainers of forks and dependent tools are kindly asked to review their code after the merge.

After the merge, a migration guide outlining the main changes and old-to-new mappings will be added to this discussion.

Since the refactoring is still in progress, we would appreciate it if pull requests that touch the common parts could be submitted after the refactoring has been merged.

There may be some temporary inconvenience, but we appreciate your understanding, as this work aims to improve long-term maintainability. Thank you.

日本語

いつも当リポジトリをご利用いただき、また多数の貢献をいただき、ありがとうございます。
現在、大規模な内部リファクタリングを進めており、間もなく完了する見込みです。近日中にmainへのマージを予定しています。

各スクリプト利用時のインターフェース（スクリプト名、コマンドラインオプション、データセット設定など）には基本的には変更ありませんので、そのままお使いいただけます。

実装面では、各アーキテクチャのクラスは基本的に維持されていますが、内部のAPI（基底クラスやユーティリティモジュールなど）は大きく変更されています。そのため、forkされたリポジトリや、依存ツールのメンテナの方々におかれましては、マージ後に確認をお願いいたします。
マージ後に、主要な変更点や新旧の対応を示した移行ガイドをこのdiscussionに追加する予定です。

pull requestにつきまして、リファクタリングが進行中のため、共通部分に関するpull requestはリファクタリングのマージ後にご提出いただければ幸いです。

一時的にご不便をおかけする場面もあるかもしれませんが、将来的な保守性を向上させるための取り組みとしてご理解いただければ幸いです。よろしくお願いいたします。

---

Migration Guide for the Large-Scale Refactoring (PR #2372)

日本語版は下にあります

Overview (English)

A large-scale internal refactoring (PR #2372, "Refactor for ai agents") has been merged into main.

• The user-facing interface of each script (script names, command-line options, dataset configuration, etc.) is essentially unchanged. Training, inference, and caching commands work as before.
• The main change is splitting the oversized library/train_util.py (~7,000 lines) into 15 focused modules by responsibility.
• library/train_util.py itself remains as a backward-compatible shim that re-exports all symbols. Access via from library import train_util and attribute reads such as train_util.HIGH_VRAM continue to work.

Who is affected

Audience	Impact	Action
End users	None in general — but a few deprecated/legacy scripts were removed (see below)	Update your invocation only if you used a removed script
Fork / extension maintainers	Imports via library.train_util are preserved by the shim, but the canonical locations have moved	Existing code keeps working; new code should import directly from the new modules

train_util.py split — symbol relocation table

Functionality in library/train_util.py moved to the modules below. Imports via train_util still work, but new code should import from the new home.

Open the symbol relocation table

Destination module	Main symbols
library.accelerator_setup	enable_high_vram, prepare_accelerator, prepare_dtype, prepare_dataset_args, patch_accelerator_for_fp16_training, HIGH_VRAM
library.args	add_sd_models_arguments, add_optimizer_arguments, add_training_arguments, add_dataset_arguments, add_sd_saving_arguments, add_masked_loss_arguments, add_dit_training_arguments, verify_training_args, verify_command_line_training_args, read_config_from_file, get_sanitized_config_or_none, resume_from_local_or_hf_if_specified
library.optimizer	get_optimizer, get_optimizer_train_eval_fn, is_schedulefree_optimizer, get_scheduler_fix, get_dummy_scheduler, append_lr_to_logs, append_lr_to_logs_with_names
library.loss	get_timesteps, get_noise_noisy_latents_and_timesteps, get_huber_threshold_if_needed, conditional_loss
library.dataset	BaseDataset, DatasetGroup, MinimalDataset, BucketManager, BucketBatchIndex, ImageInfo, AugHelper, collator_class, load_arbitrary_dataset, debug_dataset, split_train_val, glob_images, glob_images_pathlib, load_image, IMAGE_EXTENSIONS, IMAGE_TRANSFORMS
library.subset	BaseSubset, DreamBoothSubset, FineTuningSubset, ControlNetSubset
library.dreambooth_dataset	DreamBoothDataset
library.finetuning_dataset	FineTuningDataset
library.controlnet_dataset	ControlNetDataset
library.caching	cache_batch_latents, is_disk_cached_latents_is_expected, trim_and_resize_if_required, load_images_and_masks_for_caching
library.model_io	load_target_model, replace_unet_modules, model_hash, calculate_sha256, precalculate_safetensors_hashes, addnet_hash_legacy, addnet_hash_safetensors, get_git_revision_hash, load_metadata_from_safetensors, get_sai_model_spec, build_minimum_network_metadata, SS_METADATA_* constants
library.checkpoint_io	save_sd_model_on_epoch_end_or_stepwise, save_sd_model_on_train_end, save_and_remove_state_on_epoch_end, save_and_remove_state_stepwise, save_state_on_train_end, get_epoch_ckpt_name, get_step_ckpt_name, get_last_ckpt_name, default_if_none, EPOCH_* / STEP_* / LAST_STATE_NAME constants
library.sampling	sample_images, sample_images_common, sample_image_inference, get_my_scheduler, load_prompts, line_to_prompt_dict, SCHEDULER_* constants
library.hidden_states	get_hidden_states, get_hidden_states_sdxl, pool_workaround
library.logging_util	init_trackers, LossRecorder

Removed / renamed scripts

These affect user-facing invocations. Update if you ran them directly.

Removed / old	Action
train_controlnet.py	Renamed — use train_control_net.py (the old name was a duplicate that already emitted a deprecation warning)
train_textual_inversion_XTI.py / XTI_hijack.py	Removed (XTI-style training dropped). Use train_textual_inversion.py / sdxl_train_textual_inversion.py for standard Textual Inversion
sdxl_train_control_net_lllite_old.py	Removed — use sdxl_train_control_net_lllite.py
networks/merge_lora_old.py	Removed — use networks/merge_lora.py
bitsandbytes_windows/ (bundled DLLs)	Removed — recent bitsandbytes supports Windows officially, so they are no longer needed

Fine-tuning dataset metadata specification

The metadata file format read by the fine-tuning dataset (a subset with metadata_file, equivalent to the --in_json command-line argument) is now formally specified in the new document docs/dataset_metadata.md.

• The trainer only interprets the three fields parsed by library/finetuning_dataset.py (caption / tags / image_size); everything else is silently ignored. Both .json and .jsonl are supported.
• The spec is tool-agnostic: any tool, script, or AI may generate the metadata file as long as it conforms to the format.
• As a result, the scripts under finetune/ (make_captions.py (BLIP), merge_captions_to_metadata.py, merge_dd_tags_to_metadata.py, clean_captions_and_tags.py, prepare_buckets_latents.py, etc.) are now deprecated. The files remain in the repository, but their content is outdated (e.g. BLIP captioning no longer works). Going forward we specify only the metadata format, not the means of generating it. See "メタデータファイルの作成" in docs/train_README-ja.md for details.

Tests

• Legacy integration tests (tests/test_train*.py, tests/test_sdxl_train*.py, tests/test_flux_train*.py, tests/test_sd3_train*.py, etc.) were removed.
• Manual verification scripts were moved to tools/dev/.

Recommended actions (forks / extensions)

1. After the merge, run your code and check for import errors or warnings.
2. Imports from library.train_util keep working for now, but please update them to import directly from the new modules per the relocation table.
3. If you imported a symbol the shim does not re-export (internal, non-public helpers), point your import at the new module directly.
4. Please submit pull requests that touch common parts after this refactoring is merged into main.

We appreciate your patience — these changes are intended to improve long-term maintainability. Please report any issues in this Discussion.

日本語

概要

大規模な内部リファクタリング（PR #2372 "Refactor for ai agents"）を main にマージしました。

• 各スクリプトのユーザー向けインターフェース（スクリプト名・コマンドライン引数・データセット設定など）は基本的に変更ありません。 学習・推論・キャッシュのコマンドは従来どおり動作します。
• 主な変更は、肥大化していた library/train_util.py（約7,000行）を、役割ごとの15個のモジュールに分割したことです。
• library/train_util.py 自体は、全シンボルを再エクスポートする後方互換 shim として残しています。from library import train_util 経由のアクセスや train_util.HIGH_VRAM のような属性参照も、これまでどおり動作します。

影響範囲

対象	影響	対応
一般ユーザー	原則なし。ただし一部の非推奨/旧版スクリプトが削除されました（後述）	削除スクリプトを使っていた場合のみ呼び出しを変更
fork・拡張ツールの開発者	library.train_util 経由の import は shim により維持。ただし正規の置き場所（canonical location）が移動しました	当面は動作しますが、新規コードは新しいモジュールから直接 import することを推奨

train_util.py の分割 — シンボル再配置表

library/train_util.py の各機能は、以下のモジュールに移動しました。train_util 経由でも引き続き import できますが、新規コードは移動先から直接 import してください。

シンボル再配置表を開く

移動先モジュール	主なシンボル
library.accelerator_setup	enable_high_vram, prepare_accelerator, prepare_dtype, prepare_dataset_args, patch_accelerator_for_fp16_training, HIGH_VRAM
library.args	add_sd_models_arguments, add_optimizer_arguments, add_training_arguments, add_dataset_arguments, add_sd_saving_arguments, add_masked_loss_arguments, add_dit_training_arguments, verify_training_args, verify_command_line_training_args, read_config_from_file, get_sanitized_config_or_none, resume_from_local_or_hf_if_specified
library.optimizer	get_optimizer, get_optimizer_train_eval_fn, is_schedulefree_optimizer, get_scheduler_fix, get_dummy_scheduler, append_lr_to_logs, append_lr_to_logs_with_names
library.loss	get_timesteps, get_noise_noisy_latents_and_timesteps, get_huber_threshold_if_needed, conditional_loss
library.dataset	BaseDataset, DatasetGroup, MinimalDataset, BucketManager, BucketBatchIndex, ImageInfo, AugHelper, collator_class, load_arbitrary_dataset, debug_dataset, split_train_val, glob_images, glob_images_pathlib, load_image, IMAGE_EXTENSIONS, IMAGE_TRANSFORMS
library.subset	BaseSubset, DreamBoothSubset, FineTuningSubset, ControlNetSubset
library.dreambooth_dataset	DreamBoothDataset
library.finetuning_dataset	FineTuningDataset
library.controlnet_dataset	ControlNetDataset
library.caching	cache_batch_latents, is_disk_cached_latents_is_expected, trim_and_resize_if_required, load_images_and_masks_for_caching
library.model_io	load_target_model, replace_unet_modules, model_hash, calculate_sha256, precalculate_safetensors_hashes, addnet_hash_legacy, addnet_hash_safetensors, get_git_revision_hash, load_metadata_from_safetensors, get_sai_model_spec, build_minimum_network_metadata, SS_METADATA_* 定数
library.checkpoint_io	save_sd_model_on_epoch_end_or_stepwise, save_sd_model_on_train_end, save_and_remove_state_on_epoch_end, save_and_remove_state_stepwise, save_state_on_train_end, get_epoch_ckpt_name, get_step_ckpt_name, get_last_ckpt_name, default_if_none, EPOCH_* / STEP_* / LAST_STATE_NAME などの定数
library.sampling	sample_images, sample_images_common, sample_image_inference, get_my_scheduler, load_prompts, line_to_prompt_dict, SCHEDULER_* 定数
library.hidden_states	get_hidden_states, get_hidden_states_sdxl, pool_workaround
library.logging_util	init_trackers, LossRecorder

削除・改名されたスクリプト

以下はユーザー向けの呼び出しに影響します。該当スクリプトを直接実行していた場合は変更してください。

削除/旧	対応
train_controlnet.py	改名済み。train_control_net.py を使用してください（旧名は以前から非推奨警告を出していた重複スクリプトです）
train_textual_inversion_XTI.py / XTI_hijack.py	削除（XTI 方式の学習は廃止）。通常の Textual Inversion は train_textual_inversion.py / sdxl_train_textual_inversion.py を使用してください
sdxl_train_control_net_lllite_old.py	削除。sdxl_train_control_net_lllite.py を使用してください
networks/merge_lora_old.py	削除。networks/merge_lora.py を使用してください
bitsandbytes_windows/（同梱 DLL 一式）	削除。最近の bitsandbytes は Windows を公式サポートしているため不要です

fine-tuning データセットのメタデータ仕様

fine-tuning 方式のデータセット（サブセットに metadata_file を指定、またはコマンドライン引数 --in_json 相当）が読み込むメタデータファイルの形式を、新ドキュメント docs/dataset_metadata.md で明文化しました。

• 学習スクリプトが実際に解釈するのは library/finetuning_dataset.py がパースする 3 フィールド（caption / tags / image_size）のみで、それ以外は黙って無視されます。.json / .jsonl の両形式に対応します。
• 仕様はツール非依存です。形式さえ満たしていれば、任意のツール・スクリプト・AI でメタデータファイルを生成して構いません。
• これに伴い、finetune/ フォルダ内のスクリプト（make_captions.py（BLIP）、merge_captions_to_metadata.py、merge_dd_tags_to_metadata.py、clean_captions_and_tags.py、prepare_buckets_latents.py など）は非推奨となりました。ファイル自体はリポジトリに残っていますが、BLIP によるキャプショニングが現在は動作しないなど内容が古くなっています。今後はメタデータの「形式」のみを仕様とし、生成手段は規定しません。詳細は docs/train_README-ja.md の「メタデータファイルの作成」を参照してください。

テスト

• 旧来の統合テスト（tests/test_train*.py, tests/test_sdxl_train*.py, tests/test_flux_train*.py, tests/test_sd3_train*.py など）は削除しました。
• 手動確認用スクリプトは tools/dev/ に移動しました。

推奨対応（fork・拡張開発者向け）

1. マージ後にコードを実行し、import エラーや警告が出ないか確認してください。
2. library.train_util から import している箇所は当面そのまま動きますが、上記の再配置表に従って新しいモジュールから直接 import するよう更新することを推奨します。
3. もし shim が再エクスポートしていないシンボル（公開 API でない内部関数など）を import していた場合は、移動先モジュールを直接指定する必要があります。
4. 共通部分に影響する Pull Request は、このリファクタリングの main 取り込み後に提出してください。

ご不便をおかけしますが、これらの変更は長期的な保守性向上のためのものです。問題があればこの Discussion でお知らせください。

[FurkanGozukara]

great news. i was planning to make a fork to add few stuff so i can do once this is done