Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
CLI: defer YAML, asyncio, rich and the config schema build off import (#15585)
Daniel Hanf81c6b6b5942
diff --git a/scripts/risky_loaders_baseline.json b/scripts/risky_loaders_baseline.jsonindex 3ee6cebb2a3..b0788c10933 100644--- a/scripts/risky_loaders_baseline.json+++ b/scripts/risky_loaders_baseline.json@@ -782,9 +782,9 @@"file": "unsloth_cli/commands/eval.py","rule": "unsafe-deserialize","sink": "yaml.load",- "digest": "99bb2a156edb2dfc",+ "digest": "7a94da1fd84a23da","count": 1,- "reason": "_TaskYamlLoader subclasses yaml.SafeLoader; it only adds a tag for lm-eval's !function references."+ "reason": "_task_yaml_loader() returns a yaml.SafeLoader subclass; it only adds a tag for lm-eval's !function references."},{"file": "unsloth_cli/commands/studio.py",diff --git a/unsloth_cli/_inference.py b/unsloth_cli/_inference.pyindex 20ad486e680..e583dfd72d6 100644--- a/unsloth_cli/_inference.py+++ b/unsloth_cli/_inference.py@@ -3,7 +3,6 @@"""Model loading and streaming shared by `inference` and `chat`."""-import asyncioimport jsonimport osimport re@@ -611,6 +610,8 @@ def _load_gguf_backend())+ import asyncio+loaded = asyncio.run(load_with_tensor_fallback(_attempt_gguf_load,diff --git a/unsloth_cli/commands/chat.py b/unsloth_cli/commands/chat.pyindex 79609d89d3d..b5893be6293 100644--- a/unsloth_cli/commands/chat.py+++ b/unsloth_cli/commands/chat.py@@ -6,7 +6,6 @@ from types import SimpleNamespacefrom typing import List, Optionalimport typer-from rich.console import Consolefrom unsloth_cli._inference import (SpeculativeType,@@ -258,6 +257,8 @@ def chat(if not verbose:configure_quiet_logging()+ from rich.console import Console+console = Console()err = Console(stderr = True)is_mlx_distributed, rank, _world_size = mlx_distributed_info()diff --git a/unsloth_cli/commands/eval.py b/unsloth_cli/commands/eval.pyindex 3d3c8e7e376..c4901f1b152 100644--- a/unsloth_cli/commands/eval.py+++ b/unsloth_cli/commands/eval.py@@ -2,6 +2,7 @@# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0import contextlib+import functoolsimport jsonimport osimport re@@ -15,7 +16,6 @@ from pathlib import Path, PureWindowsPathfrom typing import List, Optional, Tupleimport typer-import yaml_HUB_REPO_RE = re.compile(r"[\w.\-]+/[\w.\-]+")_TOKENIZER_FILES = ("tokenizer_config.json", "tokenizer.json", "tokenizer.model")@@ -255,13 +255,17 @@ def _base_vocab_size(model: str) -> int:return getattr(getattr(config, "text_config", None) or config, "vocab_size", 0) or 0-class _TaskYamlLoader(yaml.SafeLoader):- """safe_load that tolerates lm-eval's custom tags (!function utils.fn)."""+def _task_yaml_loader():+ import yaml+ class _TaskYamlLoader(yaml.SafeLoader):+ """safe_load that tolerates lm-eval's custom tags (!function utils.fn)."""-_TaskYamlLoader.add_multi_constructor(- "!", lambda loader, suffix, node: getattr(node, "value", None)-)+ _TaskYamlLoader.add_multi_constructor(+ "!", lambda loader, suffix, node: getattr(node, "value", None)+ )+ return _TaskYamlLoaderdef _doc_column(key: str) -> str:@@ -299,15 +303,19 @@ def make_dataset_task(],"metric_list": [{"metric": "exact_match", "aggregation": "mean", "higher_is_better": True}],}+ import yaml+out_dir.mkdir(parents = True, exist_ok = True)(out_dir / f"{name}.yaml").write_text(yaml.safe_dump(spec, sort_keys = False), encoding = "utf-8")def _yaml_task_name(path: Path) -> Tuple[str, bool]:"""(registered name, needs its directory on the include path)."""+ import yaml+text = path.read_text(encoding = "utf-8")try:- spec = yaml.load(text, Loader = _TaskYamlLoader)+ spec = yaml.load(text, Loader = _task_yaml_loader())except yaml.YAMLError as e:raise ValueError(f"Invalid YAML in custom task file '{path}': {e}") from eif not isinstance(spec, dict):diff --git a/unsloth_cli/config.py b/unsloth_cli/config.pyindex 91d4fbe1191..48e69ee8735 100644--- a/unsloth_cli/config.py+++ b/unsloth_cli/config.py@@ -1,10 +1,10 @@# SPDX-License-Identifier: AGPL-3.0-only# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0+import threadingfrom pathlib import Pathfrom typing import Literal, Optional, List-import yamlfrom pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator@@ -13,7 +13,7 @@ def _lower_str(value):class DataConfig(BaseModel):- model_config = ConfigDict(extra = "forbid", validate_assignment = True)+ model_config = ConfigDict(extra = "forbid", validate_assignment = True, defer_build = True)dataset: Optional[str] = Nonelocal_dataset: Optional[List[str]] = None@@ -24,7 +24,7 @@ class DataConfig(BaseModel):class TrainingConfig(BaseModel):- model_config = ConfigDict(extra = "forbid", validate_assignment = True)+ model_config = ConfigDict(extra = "forbid", validate_assignment = True, defer_build = True)training_type: Literal["lora", "full"] = "lora"max_seq_length: int = 2048@@ -62,7 +62,7 @@ class TrainingConfig(BaseModel):class LoraConfig(BaseModel):- model_config = ConfigDict(extra = "forbid", validate_assignment = True)+ model_config = ConfigDict(extra = "forbid", validate_assignment = True, defer_build = True)lora_r: int = 64lora_alpha: int = 16@@ -79,7 +79,7 @@ class LoraConfig(BaseModel):class LoggingConfig(BaseModel):- model_config = ConfigDict(extra = "forbid", validate_assignment = True)+ model_config = ConfigDict(extra = "forbid", validate_assignment = True, defer_build = True)enable_wandb: bool = Falsewandb_project: str = "unsloth-training"@@ -90,7 +90,7 @@ class LoggingConfig(BaseModel):class Config(BaseModel):- model_config = ConfigDict(extra = "forbid", validate_assignment = True)+ model_config = ConfigDict(extra = "forbid", validate_assignment = True, defer_build = True)model: Optional[str] = Nonedata: DataConfig = Field(default_factory = DataConfig)@@ -221,8 +221,25 @@ def _config_error_message(path: Path, error: ValidationError) -> str:return "\n".join(lines)+_SCHEMA_LOCK = threading.Lock()+_schemas_built = False+++def _build_schemas() -> None:+ """Build the deferred validators once under a lock: concurrent first builds can corrupt them."""+ global _schemas_built+ if _schemas_built:+ return+ with _SCHEMA_LOCK:+ if not _schemas_built:+ for model in (DataConfig, TrainingConfig, LoraConfig, LoggingConfig, Config):+ model.model_rebuild()+ _schemas_built = True++def load_config(path: Optional[Path]) -> Config:"""Load config from YAML/JSON file, or return defaults if no path given."""+ _build_schemas()if not path:return Config()@@ -243,6 +260,7 @@ def load_config(path: Optional[Path]) -> Config:raise ConfigError(f"Could not read config file: {path}\n - {error}") from Noneif path.suffix.lower() in {".yaml", ".yml"}:+ import yamltry:data = yaml.safe_load(text)except yaml.YAMLError as error:diff --git a/unsloth_cli/tests/test_cli_import_cost.py b/unsloth_cli/tests/test_cli_import_cost.pynew file mode 100644index 00000000000..c27a7934d68--- /dev/null+++ b/unsloth_cli/tests/test_cli_import_cost.py@@ -0,0 +1,106 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Every `unsloth` invocation (`--version`, `--help`, the `studio` launcher) imports all command+modules, so their module scope stays lean: YAML, asyncio and rich load where they are used."""++from __future__ import annotations++import json+import subprocess+import sys+from pathlib import Path++_REPO_ROOT = Path(__file__).resolve().parents[2]+if str(_REPO_ROOT) not in sys.path:+ sys.path.insert(0, str(_REPO_ROOT))++DEFERRED = ("yaml", "asyncio", "rich.console")+++def _child_json(code: str):+ # cwd alone does not select this checkout under PYTHONSAFEPATH=1, so put it first on sys.path.+ probe = f"import json, sys\nsys.path.insert(0, {str(_REPO_ROOT)!r})\n{code}\n"+ result = subprocess.run(+ [sys.executable, "-c", probe],+ capture_output = True,+ text = True,+ cwd = str(_REPO_ROOT),+ timeout = 300,+ )+ assert result.returncode == 0, result.stderr+ return json.loads(result.stdout.strip().splitlines()[-1])+++def _deferred_loaded_by(statement: str) -> set[str]:+ return set(+ _child_json(+ f"{statement}\n"+ f"print(json.dumps(sorted(m for m in {DEFERRED!r} if m in sys.modules)))"+ )+ )+++def test_importing_the_cli_does_not_load_deferred_modules():+ # Only what the CLI itself adds counts: typer, click or pydantic may load these on some versions.+ preloaded = _deferred_loaded_by("import typer, click, pydantic")+ assert _deferred_loaded_by("import unsloth_cli") - preloaded == set()+++def test_config_fields_are_available_before_the_schema_is_built():+ from unsloth_cli.config import Config, load_config+ from unsloth_cli.options import _collect_config_fields++ names = {name for name, _ in _collect_config_fields(Config)}+ assert {"model", "dataset", "learning_rate", "lora_r", "hf_token"} <= names+ cfg = load_config(None)+ cfg.apply_overrides(learning_rate = 1e-4)+ assert cfg.training.learning_rate == 1e-4+++def test_yaml_config_still_loads(tmp_path):+ from unsloth_cli.config import load_config++ path = tmp_path / "config.yaml"+ path.write_text("model: unsloth/foo\ntraining:\n max_steps: 7\n", encoding = "utf-8")+ cfg = load_config(path)+ assert cfg.model == "unsloth/foo"+ assert cfg.training.max_steps == 7+++_MODELS = "(c.DataConfig, c.TrainingConfig, c.LoraConfig, c.LoggingConfig, c.Config)"+++def test_importing_the_cli_leaves_every_config_schema_unbuilt():+ built = _child_json(+ "import unsloth_cli\n"+ "import unsloth_cli.config as c\n"+ f"print(json.dumps([m.__pydantic_complete__ for m in {_MODELS}]))"+ )+ assert built == [False] * 5+++def test_concurrent_first_loads_build_the_schemas_once():+ # Racing first builds of the deferred schemas can leave a validator broken for every later call.+ errors, ok = _child_json(+ "import threading\n"+ "sys.setswitchinterval(1e-6)\n"+ "from unsloth_cli.config import load_config\n"+ "errors = []\n"+ "barrier = threading.Barrier(8)\n"+ "def run():\n"+ " try:\n"+ " barrier.wait()\n"+ " cfg = load_config(None)\n"+ " cfg.apply_overrides(learning_rate = 1e-4, lora_r = 8, max_steps = 3)\n"+ " except Exception as error:\n"+ " errors.append(repr(error))\n"+ "threads = [threading.Thread(target = run) for _ in range(8)]\n"+ "for t in threads: t.start()\n"+ "for t in threads: t.join()\n"+ "cfg = load_config(None)\n"+ "cfg.apply_overrides(learning_rate = 2e-4)\n"+ "print(json.dumps([errors, cfg.training.learning_rate == 2e-4]))"+ )+ assert errors == []+ assert ok is True