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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Live, persisted Hugging Face cache routing for Unsloth Studio.
Hugging Face reads cache environment variables at import time. Unsloth therefore
owns an explicit cache snapshot for each operation instead of trying to refresh
``huggingface_hub.constants`` in the long-running API process.
"""
from __future__ import annotations
import os
import stat
import sys
import shutil
import tempfile
import threading
from contextlib import contextmanager
from dataclasses import dataclass
from pathlib import Path
from typing import Iterator, Literal, Mapping, Optional
CACHE_HOME_SETTING_KEY = "hugging_face_cache_home"
CACHE_HISTORY_SETTING_KEY = "hugging_face_cache_history"
MAX_CACHE_HISTORY = 16
# Download to folders, kept apart from the Models folder history so neither list evicts the other.
DOWNLOAD_HOMES_SETTING_KEY = "hugging_face_download_homes"
MAX_DOWNLOAD_HOMES = 64
CacheSource = Literal["default", "studio", "environment"]
_CACHE_ENV_KEYS = (
"HF_HOME",
"HF_HUB_CACHE",
"HUGGINGFACE_HUB_CACHE",
"HF_XET_CACHE",
)
# Imported by storage_roots._setup_cache_env before Unsloth seeds defaults.
_EXPLICIT_CACHE_ENV = {
key: value.strip()
for key in _CACHE_ENV_KEYS
if (value := os.environ.get(key)) is not None and value.strip()
}
_settings_lock = threading.RLock()
_spawn_env_lock = threading.RLock()
@dataclass(frozen = True)
class HuggingFaceCachePaths:
cache_home: Path
hub_cache: Path
xet_cache: Path
source: CacheSource
environment_variable: Optional[str] = None
@property
def editable(self) -> bool:
return self.source != "environment"
@property
def is_custom(self) -> bool:
return self.source == "studio"
def child_env(self, base: Optional[Mapping[str, str]] = None) -> dict[str, str]:
# Scrub anyway: an explicit base may carry scoped offline flags from an open guard.
from utils.utils import hf_environment_for_spawn, hf_environment_scrubbed
env = hf_environment_for_spawn() if base is None else hf_environment_scrubbed(base)
# Do not rewrite HF_HOME. It also owns HF's token path.
env["HF_HUB_CACHE"] = str(self.hub_cache)
env["HF_XET_CACHE"] = str(self.xet_cache)
env.pop("HUGGINGFACE_HUB_CACHE", None)
return env
def _default_cache_home() -> Path:
xdg = (os.environ.get("XDG_CACHE_HOME") or "").strip()
return (Path(xdg).expanduser() if xdg else Path.home() / ".cache") / "huggingface"
def _canonical(path: Path | str) -> Path:
return Path(path).expanduser().resolve(strict = False)
def _environment_paths() -> Optional[HuggingFaceCachePaths]:
explicit_home = _EXPLICIT_CACHE_ENV.get("HF_HOME")
explicit_hub = _EXPLICIT_CACHE_ENV.get("HF_HUB_CACHE") or _EXPLICIT_CACHE_ENV.get(
"HUGGINGFACE_HUB_CACHE"
)
if not explicit_home and not explicit_hub:
return None
explicit_xet = _EXPLICIT_CACHE_ENV.get("HF_XET_CACHE")
default_home = _default_cache_home()
hf_home = _canonical(explicit_home) if explicit_home else default_home
hub = _canonical(explicit_hub) if explicit_hub else hf_home / "hub"
# huggingface_hub derives HF_XET_CACHE from HF_HOME, never HF_HUB_CACHE, so a hub-only override leaves chunk and shard caches in the host home.
xet_home = hf_home if explicit_home else (_portable_cache_home() or hf_home)
xet = _canonical(explicit_xet) if explicit_xet else xet_home / "xet"
controlling = next(
key
for key in ("HF_HUB_CACHE", "HUGGINGFACE_HUB_CACHE", "HF_HOME")
if key in _EXPLICIT_CACHE_ENV
)
# Explicit hub path is shown even when HF_HOME points elsewhere; Settings describes model downloads.
display_home = (
(hub.parent if explicit_hub and hub.name.lower() == "hub" else hub)
if explicit_hub
else hf_home
)
return HuggingFaceCachePaths(display_home, hub, xet, "environment", controlling)
def _absence_is_real(path: Path) -> bool:
"""On Windows FileNotFoundError can mean a parent is a file, so absence needs a real directory above."""
current = os.path.dirname(os.fspath(path))
while current:
try:
info = os.stat(current)
except FileNotFoundError:
parent = os.path.dirname(current)
if parent == current:
return True
current = parent
continue
except OSError:
return False
return stat.S_ISDIR(info.st_mode)
return True
def _stored_cache_home() -> Optional[Path]:
# get_app_setting creates studio.db, so skip only on an observed absence (os.stat).
# Not Path.exists (3.14 hides EACCES/EIO) nor lstat (sqlite follows symlinks).
try:
if "storage.studio_db" not in sys.modules:
from utils.paths.storage_roots import studio_db_path
database = studio_db_path()
try:
os.stat(database)
except FileNotFoundError:
if _absence_is_real(database):
return None
except Exception: # noqa: BLE001 - fall through to the read on any doubt
pass
try:
from storage.studio_db import get_app_setting
from utils.account_context import OWNER, run_as
value = run_as(OWNER, get_app_setting, CACHE_HOME_SETTING_KEY, None)
except Exception: # noqa: BLE001 - the shim is optional; a spawn must never depend on it
return None
if not isinstance(value, str) or not value.strip():
return None
try:
return _canonical(value.strip())
except (OSError, RuntimeError, ValueError):
return None
def configured_cache_key() -> str:
"""Not resolved on purpose: resolve() can block on the volume being moved off; only equality matters."""
explicit = (
_EXPLICIT_CACHE_ENV.get("HF_HUB_CACHE")
or _EXPLICIT_CACHE_ENV.get("HUGGINGFACE_HUB_CACHE")
or _EXPLICIT_CACHE_ENV.get("HF_HOME")
)
if explicit:
return "env:" + explicit
try:
from storage.studio_db import get_app_setting
from utils.account_context import OWNER, run_as
value = run_as(OWNER, get_app_setting, CACHE_HOME_SETTING_KEY, None)
except Exception:
return "default"
if isinstance(value, str) and value.strip():
return "studio:" + value.strip()
return "default"
def _portable_cache_home() -> Optional[Path]:
"""HF cache home for a portable install, else None: normal installs keep the platform default,
so shared models are not re-downloaded; lazy import; storage_roots imports this module."""
try:
from utils.paths.storage_roots import cache_root, portable_mode
except ImportError:
return None
if not portable_mode():
return None
try:
return _canonical(cache_root() / "huggingface")
except (OSError, RuntimeError, ValueError):
return None
def _scan_memoized(name: str, compute):
from utils.scan_memo import memoized
environ = os.environ
key = (
name,
environ.get("HOME"),
environ.get("XDG_CACHE_HOME"),
environ.get("UNSLOTH_PORTABLE"),
environ.get("UNSLOTH_HOME"),
)
return memoized(key, compute)
def get_hf_cache_paths() -> HuggingFaceCachePaths:
return _scan_memoized("hf_cache_paths", _get_hf_cache_paths_uncached)
def _get_hf_cache_paths_uncached() -> HuggingFaceCachePaths:
env_paths = _environment_paths()
if env_paths is not None:
return env_paths
stored = _stored_cache_home()
if stored is not None:
xet = _EXPLICIT_CACHE_ENV.get("HF_XET_CACHE")
return HuggingFaceCachePaths(
stored,
stored / "hub",
_canonical(xet) if xet else stored / "xet",
"studio",
)
# Ranks below env vars and Settings: portable mode is a default, not an override.
home = _portable_cache_home() or _default_cache_home()
xet = _EXPLICIT_CACHE_ENV.get("HF_XET_CACHE")
return HuggingFaceCachePaths(
home,
home / "hub",
_canonical(xet) if xet else home / "xet",
"default",
)
def active_hf_hub_cache() -> str:
"""Return the current hub cache as a string for library call kwargs."""
return str(get_hf_cache_paths().hub_cache)
@contextmanager
def _xet_loader_barrier() -> Iterator[None]:
"""Block while a Xet shim loader holds its process-wide env override. Never fails a spawn."""
try:
from utils.hf_xet_fallback import env_override_barrier
barrier = env_override_barrier()
except Exception: # noqa: BLE001 - the shim is optional; a spawn must never depend
yield
return
with barrier:
yield
@contextmanager
def child_environment_for_spawn(environment: Mapping[str, str]) -> Iterator[None]:
"""Env must be set before spawn imports the child, since some libraries snapshot it at import."""
from utils.utils import hf_environment_restored_for_spawn
# Avoid the Xet shim's GPU-init override window: children would inherit stub triton/bnb.
with _spawn_env_lock, _xet_loader_barrier(), hf_environment_restored_for_spawn():
missing = object()
saved_environment: dict[str, str | object] = {}
for key, value in environment.items():
saved_environment[key] = os.environ.get(key, missing)
os.environ[key] = value
try:
yield
finally:
for key, previous in saved_environment.items():
if previous is missing:
os.environ.pop(key, None)
else:
os.environ[key] = str(previous)
def initialize_hf_cache_environment() -> HuggingFaceCachePaths:
"""Seed import-time HF variables once during backend startup."""
paths = get_hf_cache_paths()
# Keep an explicit HF_HOME; else credentials stay at the platform default; cache routes to the home.
if not os.environ.get("HF_HOME", "").strip():
os.environ["HF_HOME"] = str(_default_cache_home())
os.environ["HF_HUB_CACHE"] = str(paths.hub_cache)
os.environ["HF_XET_CACHE"] = str(paths.xet_cache)
if "HUGGINGFACE_HUB_CACHE" not in _EXPLICIT_CACHE_ENV:
os.environ.pop("HUGGINGFACE_HUB_CACHE", None)
for directory in (paths.hub_cache, paths.xet_cache):
try:
directory.mkdir(parents = True, exist_ok = True)
except OSError:
pass
return paths
def _validate_cache_home(raw_path: str) -> Path:
value = raw_path.strip()
if not value:
raise ValueError("Choose a cache folder.")
candidate = Path(value).expanduser()
if not candidate.is_absolute():
raise ValueError("The Hugging Face cache folder must be an absolute path.")
try:
resolved = candidate.resolve(strict = False)
except (OSError, RuntimeError, ValueError) as exc:
raise ValueError("The Hugging Face cache folder is invalid.") from exc
if resolved.parent == resolved:
raise ValueError("Choose a folder inside the filesystem or drive root.")
try:
from hub.storage.scan_folders import (
contains_sensitive_path_component,
is_denied_system_path,
)
except ImportError:
contains_sensitive_path_component = is_denied_system_path = None
if is_denied_system_path is not None and is_denied_system_path(str(resolved)):
raise ValueError("System folders cannot be used for model downloads.")
if contains_sensitive_path_component is not None and contains_sensitive_path_component(
str(resolved)
):
raise ValueError("Credential or config folders cannot be used for model downloads.")
parent = resolved.parent
if not parent.exists() or not parent.is_dir():
raise ValueError("The parent folder does not exist.")
try:
resolved.mkdir(exist_ok = True)
if not resolved.is_dir():
raise ValueError("The selected cache location is not a folder.")
for child in (resolved / "hub", resolved / "xet"):
child.mkdir(exist_ok = True)
with tempfile.NamedTemporaryFile(prefix = ".unsloth-write-test-", dir = child):
pass
except PermissionError as exc:
raise ValueError("Unsloth does not have permission to write to this folder.") from exc
except OSError as exc:
raise ValueError(f"Unsloth cannot use this cache folder: {exc}") from exc
return resolved
def _stored_history() -> list[Path]:
return _stored_paths(CACHE_HISTORY_SETTING_KEY, MAX_CACHE_HISTORY)
def _stored_download_homes() -> list[Path]:
return _stored_paths(DOWNLOAD_HOMES_SETTING_KEY, MAX_DOWNLOAD_HOMES)
def _stored_paths(setting_key: str, limit: int) -> list[Path]:
try:
from storage.studio_db import get_app_setting
from utils.account_context import OWNER, run_as
raw = run_as(OWNER, get_app_setting, setting_key, [])
except Exception:
raw = []
if not isinstance(raw, list):
return []
out: list[Path] = []
seen: set[str] = set()
for value in raw:
if not isinstance(value, str) or not value.strip():
continue
try:
path = _canonical(value)
except (OSError, RuntimeError, ValueError):
continue
key = os.path.normcase(str(path))
if key in seen:
continue
seen.add(key)
out.append(path)
return out[:limit]
def set_hf_cache_home(cache_home: Optional[str]) -> HuggingFaceCachePaths:
if _environment_paths() is not None:
raise RuntimeError("The Hugging Face cache location is managed by an environment variable.")
with _settings_lock:
previous = _stored_cache_home()
next_home = _validate_cache_home(cache_home) if cache_home is not None else None
history = _stored_history()
if previous is not None and previous != next_home:
history.insert(0, previous)
deduped: list[str] = []
seen: set[str] = set()
for path in history:
key = os.path.normcase(str(path))
if key in seen or path == next_home:
continue
seen.add(key)
deduped.append(str(path))
if len(deduped) >= MAX_CACHE_HISTORY:
break
from storage.studio_db import upsert_app_settings
upsert_app_settings(
{
CACHE_HOME_SETTING_KEY: str(next_home) if next_home is not None else None,
CACHE_HISTORY_SETTING_KEY: deduped,
}
)
_invalidate_cache_views()
return get_hf_cache_paths()
def download_cache_paths(download_dir: Optional[str]) -> HuggingFaceCachePaths:
"""Cache paths for one download: the Models folder, or a chosen folder laid out the same way;
raises ValueError for a folder the Models setting would refuse."""
active = get_hf_cache_paths()
if download_dir is None or not download_dir.strip():
return active
home = _validate_cache_home(download_dir)
if os.path.normcase(str(home)) == os.path.normcase(str(_canonical(active.cache_home))):
return active
xet = _EXPLICIT_CACHE_ENV.get("HF_XET_CACHE")
return HuggingFaceCachePaths(
home,
home / "hub",
_canonical(xet) if xet else home / "xet",
"studio",
)
def remember_cache_home(cache_home: Path) -> None:
"""Keeps a download folder among the known caches, like a previous Models folder; progress,
resume, delete and cached-model checks read only known caches. Idempotent."""
home = _canonical(cache_home)
key = os.path.normcase(str(home))
with _settings_lock:
homes = _stored_download_homes()
if len(homes) >= MAX_DOWNLOAD_HOMES or any(
os.path.normcase(str(path)) == key for path in homes
):
return
from storage.studio_db import upsert_app_settings
from utils.account_context import OWNER, run_as
run_as(
OWNER,
upsert_app_settings,
{DOWNLOAD_HOMES_SETTING_KEY: [*(str(path) for path in homes), str(home)]},
)
_invalidate_cache_views()
def _invalidate_cache_views() -> None:
# Inventory scans are cached apart from settings, so invalidate after persisting them.
from hub.utils.inventory_scan import invalidate_hf_cache_scans
invalidate_hf_cache_scans()
# Partial resumability depends on the filesystem, so it is re-decided for the new root, not reused.
from hub.utils.hf_cache_state import invalidate_partial_resumability
invalidate_partial_resumability()
# And the inventory's remembered sizes, which are keyed by cache rather than by path.
from utils.cache_inventory import invalidate_hf_rooted_sizes
invalidate_hf_rooted_sizes()
def effective_cache_home() -> Path:
"""The real HF_HOME, not the display cache_home; the token, assets and datasets stay under it."""
live = (os.environ.get("HF_HOME") or "").strip()
return _canonical(live) if live else _default_cache_home()
def known_hf_cache_homes() -> list[Path]:
return list(_scan_memoized("known_hf_cache_homes", _known_hf_cache_homes))
def _known_hf_cache_homes() -> list[Path]:
paths = get_hf_cache_paths()
stored = _stored_cache_home()
candidates: list[Path] = []
if paths.source != "environment":
candidates.append(paths.cache_home)
elif explicit_home := _EXPLICIT_CACHE_ENV.get("HF_HOME"):
candidates.append(_canonical(explicit_home))
if stored is not None:
candidates.append(stored)
candidates.extend([*_stored_history(), *_stored_download_homes(), _default_cache_home()])
out: list[Path] = []
seen: set[str] = set()
for candidate in candidates:
try:
canonical = _canonical(candidate)
except (OSError, RuntimeError, ValueError):
continue
key = os.path.normcase(str(canonical))
if key in seen:
continue
seen.add(key)
out.append(canonical)
return out
def known_hf_hub_caches() -> list[Path]:
return list(_scan_memoized("known_hf_hub_caches", _known_hf_hub_caches))
def _known_hf_hub_caches() -> list[Path]:
active = get_hf_cache_paths()
out = [active.hub_cache]
seen = {os.path.normcase(str(_canonical(active.hub_cache)))}
for home in known_hf_cache_homes():
hub = _canonical(home / "hub")
key = os.path.normcase(str(hub))
if key not in seen:
seen.add(key)
out.append(hub)
return out
def cache_status(paths: Optional[HuggingFaceCachePaths] = None) -> dict:
paths = paths or get_hf_cache_paths()
available = paths.cache_home.is_dir()
writable = available and os.access(paths.cache_home, os.W_OK | os.X_OK)
free_bytes: Optional[int] = None
if available:
try:
free_bytes = int(shutil.disk_usage(paths.cache_home).free)
except OSError:
pass
return {
"cache_home": str(paths.cache_home),
"hub_cache": str(paths.hub_cache),
"xet_cache": str(paths.xet_cache),
"source": paths.source,
"editable": paths.editable,
"is_custom": paths.is_custom,
"available": available,
"writable": writable,
"free_bytes": free_bytes,
"environment_variable": paths.environment_variable,
}