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.

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.py
index 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) -> dic
return 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.py
index 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 has
diff --git a/studio/backend/tests/test_launch_models_dir.py b/studio/backend/tests/test_launch_models_dir.py
new file mode 100644
index 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() == before
diff --git a/tests/studio/test_cli_models_dir.py b/tests/studio/test_cli_models_dir.py
new file mode 100644
index 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_decls
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index 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: