Skip to content

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.

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.json
index 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.py
index 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 asyncio
import json
import os
import 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.py
index 79609d89d3d..b5893be6293 100644
--- a/unsloth_cli/commands/chat.py
+++ b/unsloth_cli/commands/chat.py
@@ -6,7 +6,6 @@ from types import SimpleNamespace
from typing import List, Optional
import typer
-from rich.console import Console
from 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.py
index 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.0
import contextlib
+import functools
import json
import os
import re
@@ -15,7 +16,6 @@ from pathlib import Path, PureWindowsPath
from typing import List, Optional, Tuple
import 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 _TaskYamlLoader
def _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 e
if not isinstance(spec, dict):
diff --git a/unsloth_cli/config.py b/unsloth_cli/config.py
index 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 threading
from pathlib import Path
from typing import Literal, Optional, List
-import yaml
from 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] = None
local_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 = 64
lora_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 = False
wandb_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] = None
data: 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 None
if path.suffix.lower() in {".yaml", ".yml"}:
+ import yaml
try:
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.py
new file mode 100644
index 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