From f4f69f16a639824a9d74435b2f25ef70210a45c5 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sat, 14 Mar 2026 08:53:02 +0000
Subject: [PATCH] studio: centralize cache directory for all downloads

Set HF_HOME, HF_HUB_CACHE, HF_XET_CACHE, UV_CACHE_DIR, and
VLLM_CACHE_ROOT to a unified location under ~/.unsloth/studio/cache/
on startup. This keeps all model downloads, datasets, and caches
in one place instead of scattered across ~/.cache/huggingface,
~/.cache/uv, etc.

Layout:
  ~/.unsloth/studio/cache/
    huggingface/       (HF_HOME)
      hub/             (HF_HUB_CACHE -- model/dataset downloads)
      xet/             (HF_XET_CACHE -- xet blob store)
    uv/                (UV_CACHE_DIR -- uv package cache)
    vllm/              (VLLM_CACHE_ROOT -- vllm compiled kernels)

Only sets variables that are not already in the environment, so
user overrides (e.g. HF_HOME=/data/models) are respected.

Cross-platform: uses Path.home() which resolves correctly on
Linux (~), macOS (~), and Windows (C:\Users\<user>).
---
 studio/backend/utils/paths/storage_roots.py | 29 +++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/studio/backend/utils/paths/storage_roots.py b/studio/backend/utils/paths/storage_roots.py
index d9adce2105..25210b81f9 100644
--- a/studio/backend/utils/paths/storage_roots.py
+++ b/studio/backend/utils/paths/storage_roots.py
@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import os
 from pathlib import Path
 import tempfile
 
@@ -11,6 +12,11 @@ def studio_root() -> Path:
     return Path.home() / ".unsloth" / "studio"
 
 
+def cache_root() -> Path:
+    """Central cache directory for all studio downloads (models, datasets, etc.)."""
+    return Path.home() / ".unsloth" / "studio" / "cache"
+
+
 def assets_root() -> Path:
     return studio_root() / "assets"
 
@@ -68,6 +74,28 @@ def ensure_dir(path: Path) -> Path:
     return path
 
 
+def _setup_cache_env() -> None:
+    """Set cache environment variables for HuggingFace, uv, and vLLM.
+
+    Only sets variables that are not already set by the user, so
+    explicit overrides (e.g. HF_HOME=/data/hf) are respected.
+    Works on Linux, macOS, and Windows.
+    """
+    root = cache_root()
+    hf_dir = root / "huggingface"
+    defaults = {
+        "HF_HOME":         str(hf_dir),
+        "HF_HUB_CACHE":    str(hf_dir / "hub"),
+        "HF_XET_CACHE":    str(hf_dir / "xet"),
+        "UV_CACHE_DIR":    str(root / "uv"),
+        "VLLM_CACHE_ROOT": str(root / "vllm"),
+    }
+    for key, value in defaults.items():
+        if key not in os.environ:
+            os.environ[key] = value
+            Path(value).mkdir(parents = True, exist_ok = True)
+
+
 def ensure_studio_directories() -> None:
     """Create all standard studio directories on startup."""
     for dir_fn in (
@@ -82,6 +110,7 @@ def ensure_studio_directories() -> None:
         tensorboard_root,
     ):
         ensure_dir(dir_fn())
+    _setup_cache_env()
 
 
 def _clean_relative_path(