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.

19.1 KB
Raw Blame
# 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,
    }