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
Studio: add --models-dir to unsloth studio for local model folders (#13435)
Daniel Han318ab67efbb7
diff --git a/studio/backend/hub/services/models/local_inventory.py b/studio/backend/hub/services/models/local_inventory.pyindex 1d37e9765ad..956bbc45348 100644--- a/studio/backend/hub/services/models/local_inventory.py+++ b/studio/backend/hub/services/models/local_inventory.py@@ -1579,6 +1579,38 @@ def add_scan_folder_response(path: str, recursive: Optional[bool] = None) -> dicreturn folder+LAUNCH_MODELS_DIRS_ENV = "UNSLOTH_STUDIO_MODELS_DIRS"+++def register_launch_scan_folders(raw: Optional[str] = None) -> list[str]:+ """Add the ``unsloth studio --models-dir`` folders (os.pathsep-joined) as Custom Folders.+ Re-launching with the same folder is a no-op; a rejected folder is logged, never fatal."""+ if raw is None:+ raw = os.environ.get(LAUNCH_MODELS_DIRS_ENV, "")+ added: list[str] = []+ for path in (p.strip() for p in raw.split(os.pathsep)):+ if not path:+ continue+ try:+ folder, inserted = add_scan_folder_with_status(_coerce_scan_folder_path(path))+ except ValueError as e:+ logger.warning(+ "--models-dir folder skipped: %s (path=%s)",+ scrub_paths(e),+ short_path_for_log(path),+ )+ continue+ if inserted:+ added.append(folder["path"])+ logger.info(+ "Scan folder added from --models-dir: %s", short_path_for_log(folder["path"])+ )+ if added:+ from core.inference.local_model_resolver import invalidate_index+ invalidate_index()+ return added++def remove_scan_folder_response(folder_id: int) -> dict:removed = remove_scan_folder(folder_id)if removed:diff --git a/studio/backend/main.py b/studio/backend/main.pyindex 78886380aa2..da7fb4d6fea 100644--- a/studio/backend/main.py+++ b/studio/backend/main.py@@ -867,6 +867,12 @@ async def lifespan(app: FastAPI):except Exception as exc:_lifespan_log.warning("reconcile_orphaned_ingestion_jobs failed at startup: %s", exc)+ try:+ from hub.services.models.local_inventory import register_launch_scan_folders+ _run_as(_owner_account, register_launch_scan_folders)+ except Exception as exc:+ _lifespan_log.warning("--models-dir registration failed at startup: %s", exc)+try:# The boot pass above only settles runs orphaned by the previous process. A run that wedges while this one# keeps serving needs the same reconciliation on an interval, bounded to runs whose progress lease hasdiff --git a/studio/backend/tests/test_launch_models_dir.py b/studio/backend/tests/test_launch_models_dir.pynew file mode 100644index 00000000000..5dd75cdf011--- /dev/null+++ b/studio/backend/tests/test_launch_models_dir.py@@ -0,0 +1,53 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""`unsloth studio --models-dir` registers Custom Folders at startup (#8250)."""++import os++import pytest++from hub.services.models import local_inventory+from storage import studio_db++[email protected](autouse = True)+def _registrable_tmp(monkeypatch):+ # macOS denies /private/var, where pytest keeps tmp_path.+ from hub.storage import scan_folders+ monkeypatch.setattr(studio_db, "_denied_path_prefixes", lambda: [])+ monkeypatch.setattr(scan_folders, "_denied_path_prefixes", lambda: [])+++def _registered() -> set[str]:+ return {row["path"] for row in studio_db.list_scan_folders()}+++def test_folders_from_env_are_registered_once(tmp_path, monkeypatch):+ a, b = tmp_path / "a", tmp_path / "b"+ a.mkdir()+ b.mkdir()+ monkeypatch.setenv(local_inventory.LAUNCH_MODELS_DIRS_ENV, os.pathsep.join([str(a), str(b)]))++ added = local_inventory.register_launch_scan_folders()+ assert set(added) == {str(a.resolve()), str(b.resolve())}+ assert {str(a.resolve()), str(b.resolve())} <= _registered()++ before = studio_db.list_scan_folders()+ assert local_inventory.register_launch_scan_folders() == []+ assert studio_db.list_scan_folders() == before+++def test_rejected_folder_is_skipped_not_fatal(tmp_path):+ good = tmp_path / "good"+ good.mkdir()+ raw = os.pathsep.join([str(tmp_path / "missing"), str(good)])+ assert local_inventory.register_launch_scan_folders(raw) == [str(good.resolve())]+ assert str((tmp_path / "missing").resolve()) not in _registered()+++def test_unset_env_is_a_no_op(monkeypatch):+ monkeypatch.delenv(local_inventory.LAUNCH_MODELS_DIRS_ENV, raising = False)+ before = studio_db.list_scan_folders()+ assert local_inventory.register_launch_scan_folders() == []+ assert studio_db.list_scan_folders() == beforediff --git a/tests/studio/test_cli_models_dir.py b/tests/studio/test_cli_models_dir.pynew file mode 100644index 00000000000..2a97895f2b1--- /dev/null+++ b/tests/studio/test_cli_models_dir.py@@ -0,0 +1,66 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""`unsloth studio --models-dir` hands its folders to the backend through the env (#8250)."""++from __future__ import annotations++import os++import pytest+import typer++import unsloth_cli.commands.studio as studio_cli++ENV = "UNSLOTH_STUDIO_MODELS_DIRS"+++def test_no_flag_leaves_env_alone(monkeypatch):+ monkeypatch.delenv(ENV, raising = False)+ studio_cli._export_models_dirs(None)+ studio_cli._export_models_dirs([])+ assert ENV not in os.environ+++def test_folders_are_resolved_and_exported(tmp_path, monkeypatch):+ monkeypatch.delenv(ENV, raising = False)+ a, b = tmp_path / "a", tmp_path / "b"+ a.mkdir()+ b.mkdir()+ studio_cli._export_models_dirs([a, b, a])+ assert os.environ[ENV].split(os.pathsep) == [str(a.resolve()), str(b.resolve())]+++def test_existing_env_is_kept(tmp_path, monkeypatch):+ a = tmp_path / "a"+ a.mkdir()+ monkeypatch.setenv(ENV, "/already/set")+ studio_cli._export_models_dirs([a])+ assert os.environ[ENV].split(os.pathsep) == ["/already/set", str(a.resolve())]+++def test_missing_folder_exits_before_launch(tmp_path, monkeypatch):+ monkeypatch.delenv(ENV, raising = False)+ with pytest.raises(typer.Exit) as exc:+ studio_cli._export_models_dirs([tmp_path / "nope"])+ assert exc.value.exit_code == 2+ assert ENV not in os.environ+++def test_folder_name_with_pathsep_is_refused(tmp_path, monkeypatch):+ monkeypatch.delenv(ENV, raising = False)+ odd = tmp_path / f"qwen{os.pathsep}Q4"+ try:+ odd.mkdir()+ except OSError:+ pytest.skip("this filesystem cannot name a folder with the path separator")+ with pytest.raises(typer.Exit) as exc:+ studio_cli._export_models_dirs([odd])+ assert exc.value.exit_code == 2+ assert ENV not in os.environ+++def test_option_is_registered_on_studio():+ import inspect+ param = inspect.signature(studio_cli.studio_default).parameters["models_dir"]+ assert "--models-dir" in param.default.param_declsdiff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.pyindex f98e2fe1404..5258f926278 100644--- a/unsloth_cli/commands/studio.py+++ b/unsloth_cli/commands/studio.py@@ -1809,6 +1809,33 @@ def _format_context_length_line(load_result: dict) -> Optional[str]:return f" Context length: {value_int} tokens"+_MODELS_DIRS_ENV = "UNSLOTH_STUDIO_MODELS_DIRS"+++def _export_models_dirs(models_dir: Optional[List[Path]]) -> None:+ """Hand --models-dir to the backend through the env, which both launch paths keep; the backend adds each as a Custom Folder."""+ if not models_dir:+ return+ resolved = []+ for raw in models_dir:+ path = Path(raw).expanduser()+ if not path.is_dir():+ typer.echo(f"Error: --models-dir {raw} is not an existing folder.", err = True)+ raise typer.Exit(2)+ resolved_path = str(path.resolve())+ if os.pathsep in resolved_path:+ typer.echo(+ f"Error: --models-dir {raw} contains '{os.pathsep}', which cannot be passed "+ "to Studio. Rename the folder or add it from Custom Folders in the model picker.",+ err = True,+ )+ raise typer.Exit(2)+ resolved.append(resolved_path)+ existing = [p for p in os.environ.get(_MODELS_DIRS_ENV, "").split(os.pathsep) if p]+ merged = list(dict.fromkeys(existing + resolved))+ os.environ[_MODELS_DIRS_ENV] = os.pathsep.join(merged)++@studio_app.callback(invoke_without_command = True)def studio_default(ctx: typer.Context,@@ -1886,11 +1913,19 @@ def studio_default("`--password -` to read one line from stdin. A literal value is visible in the ""process list and shell history. Rotate later with `unsloth studio reset-password`.",),+ models_dir: Optional[List[Path]] = typer.Option(+ None,+ "--models-dir",+ help = "Add a folder of local models to Studio (repeatable). It is saved as a "+ "Custom Folder, so its models show up in the Chat and Train model pickers on this "+ "and later launches; remove it from Custom Folders in the model picker.",+ ),):"""Launch the Unsloth Studio server."""# --not-secure is a deprecated alias for --no-secure.secure = _resolve_secure(secure, not_secure)_ensure_studio_env_exported()+ _export_models_dirs(models_dir)if ctx.invoked_subcommand is not None:# Typer does not forward parent options, so `unsloth studio --parallel N run` would drop N.if parallel != _PARALLEL_DEFAULT_PLAIN: