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
from __future__ import annotations
import http.client
import json
import logging
import os
import platform
import re
import shutil
import subprocess
import sys
import tempfile
import urllib.error
import urllib.parse
import urllib.request
from typing import Callable
from utils.native_path_leases import child_env_without_native_path_secret
from utils.child_stdio import utf8_child_env
from utils.subprocess_compat import windows_hidden_subprocess_kwargs
_logger = logging.getLogger(__name__)
FLASH_ATTN_RELEASE_BASE_URL = "https://github.com/Dao-AILab/flash-attention/releases/download"
# Pinned wheels; utils.kernel_install wraps them for the training worker, SSM runtime and CLI.
CAUSAL_CONV1D_PACKAGE_VERSION = "1.6.1"
CAUSAL_CONV1D_RELEASE_TAG = "v1.6.1.post4"
CAUSAL_CONV1D_RELEASE_BASE_URL = "https://github.com/Dao-AILab/causal-conv1d/releases/download"
MAMBA_SSM_PACKAGE_VERSION = "2.3.1"
MAMBA_SSM_RELEASE_TAG = "v2.3.1"
MAMBA_SSM_RELEASE_BASE_URL = "https://github.com/state-spaces/mamba/releases/download"
# No arch gate, deliberately: has_blackwell_gpu() skipped flash-attn before sm_100+ wheels existed (#5420) and became the bug once they did (#6961), denying B200 hosts a working wheel. An arch gate encodes a snapshot of what upstream ships and goes stale silently both ways; the post-install import check catches a wheel that will not load whatever the cause.
def wheel_platform_tag() -> str | None:
"""pip platform tag for this host, or None where nothing we resolve is published. Windows is included because download.pytorch.org publishes CUDA-matched ``win_amd64`` xFormers wheels (see ``xformers_wheel_url``), and flash-attn / causal-conv1d / mamba-ssm resolve only to the Windows wheels listed in this module; ``probe_torch_wheel_env`` keeps the per-caller opt-in, not this function."""
machine = platform.machine().lower()
if sys.platform.startswith("linux"):
if machine in {"x86_64", "amd64"}:
return "linux_x86_64"
if machine in {"aarch64", "arm64"}:
return "linux_aarch64"
elif sys.platform == "win32":
if machine in {"x86_64", "amd64"}:
return "win_amd64"
if machine in {"arm64", "aarch64"}:
return "win_arm64"
# No prebuilt wheels published for macOS
return None
def _loaded_torch_wheel_env() -> dict[str, str] | None:
"""The probe child's fields from the already imported torch, or None. Keep in step with the child below."""
torch = sys.modules.get("torch")
if torch is None:
return None
try:
import re
import sysconfig
parts = torch.__version__.split("+", 1)[0].split(".")[:2]
minor = re.sub(r"[^0-9].*", "", parts[1]) if len(parts) > 1 else "0"
cuda = torch.version.cuda
hip = getattr(torch.version, "hip", None)
py_tag = f"cp{sys.version_info.major}{sys.version_info.minor}"
return {
"python_tag": py_tag,
"abi_tag": py_tag + ("t" if sysconfig.get_config_var("Py_GIL_DISABLED") else ""),
"torch_mm": parts[0] + "." + minor,
"torch_version": str(torch.__version__),
"cuda_version": str(cuda) if cuda else "",
"cuda_major": str(int(str(cuda).split(".", 1)[0])) if cuda else "",
"hip_version": str(hip) if hip else "",
"cxx11abi": str(torch._C._GLIBCXX_USE_CXX11_ABI).upper(),
}
except Exception:
return None
def probe_torch_wheel_env(
*,
timeout: int | None = None,
include_windows: bool = False,
reuse_loaded_torch: bool = False,
) -> dict[str, str] | None:
"""Describe the resident torch build for wheel-URL resolution, or None. Windows is opt-in via ``include_windows``, for callers whose every Windows URL names a published asset. ``reuse_loaded_torch`` reads an already imported torch instead of a 1-3 s child import."""
platform_tag = wheel_platform_tag()
if platform_tag is None:
return None
if platform_tag.startswith("win_") and not include_windows:
return None
if reuse_loaded_torch:
env = _loaded_torch_wheel_env()
if env is not None:
env["platform_tag"] = platform_tag
return env
try:
probe = subprocess.run(
[
sys.executable,
"-c",
(
"import json, sys, sysconfig, re, torch; "
"parts = torch.__version__.split('+', 1)[0].split('.')[:2]; "
"minor = re.sub(r'[^0-9].*', '', parts[1]) if len(parts) > 1 else '0'; "
"torch_mm = parts[0] + '.' + minor; "
"print(json.dumps({"
"'python_tag': f'cp{sys.version_info.major}{sys.version_info.minor}', "
# Differs from python_tag only on a free-threaded build (cp314t).
"'abi_tag': f'cp{sys.version_info.major}{sys.version_info.minor}' + ('t' if sysconfig.get_config_var('Py_GIL_DISABLED') else ''), "
"'torch_mm': torch_mm, "
# xFormers publishes one wheel per exact torch PATCH and per CUDA MINOR, so 'torch_mm' / 'cuda_major' cannot pick between them. Full release + full CUDA version: cu126 and cu128 are different builds of the same version string.
"'torch_version': str(torch.__version__), "
"'cuda_version': str(torch.version.cuda) if torch.version.cuda else '', "
"'cuda_major': str(int(str(torch.version.cuda).split('.', 1)[0])) if torch.version.cuda else '', "
"'hip_version': str(torch.version.hip) if getattr(torch.version, 'hip', None) else '', "
"'cxx11abi': str(torch._C._GLIBCXX_USE_CXX11_ABI).upper()"
"}))"
),
],
stdout = subprocess.PIPE,
stderr = subprocess.PIPE,
text = True,
encoding = "utf-8",
errors = "replace",
timeout = timeout,
env = utf8_child_env(child_env_without_native_path_secret()),
**windows_hidden_subprocess_kwargs(),
)
except subprocess.TimeoutExpired:
return None
if probe.returncode != 0:
return None
try:
env = json.loads(probe.stdout.strip())
except json.JSONDecodeError:
return None
env["platform_tag"] = platform_tag
return env
# torch 2.11/2.12 ship no native prebuilt flash-attn / causal-conv1d / mamba-ssm wheels, but the torch2.10 CUDA wheels load and pass each project's own suite on both, so they are reused. The window is bounded, not open ended: torch broke extension ABI between 2.9 and 2.10, so every new key here must be measured against the real wheels before it is added. Measured on B200, py3.12, torch 2.12.1+cu130: causal-conv1d 9412 passed / 3888 skipped / 0 failed, mamba tests/ops 20 passed, flash-attn splitkv+qkvpacked 848 passed, identical to a torch 2.10 control; the torch2.9 flash-attn .so raises "undefined symbol" on torch 2.10 and 2.12 alike.
_PREBUILT_WHEEL_TORCH_MM = {"2.11": "2.10", "2.12": "2.10"}
def prebuilt_wheel_torch_mm(torch_mm: str) -> str:
"""Map a torch major.minor to the one whose prebuilt accelerator wheels to use."""
return _PREBUILT_WHEEL_TORCH_MM.get(torch_mm, torch_mm)
# ── Wheels we build ourselves ─────────────────────────────────────────────────
# torch 2.13+ broke the extension ABI again, so we build these wheels ourselves
# (.github/workflows/prebuilt-cuda-wheels.yml) and resolve to our own release.
UNSLOTH_PREBUILT_RELEASE_BASE_URL = "https://github.com/unslothai/unsloth/releases/download"
UNSLOTH_PREBUILT_RELEASE_TAG = "prebuilt-wheels-cu13"
# mamba_ssm with no compiled extension (MAMBA_KEEP_CUDA_BUILD unset), one py3-none-any wheel for every
# torch, interpreter and platform. Its Triton kernels are all the Mamba-2 mixers call; unsloth_zoo
# serves their causal conv (prefill, fused training path, decode) on Triton, so with a zoo that has
# those drop-ins the Mamba-2 hybrids need neither CUDA wheel. Built and signed by
# prebuilt-cuda-wheels.yml on the same tag.
MAMBA_SSM_PURE_VERSION = "2.3.2.post1"
MAMBA_SSM_PURE_WHEEL = f"mamba_ssm-{MAMBA_SSM_PURE_VERSION}-py3-none-any.whl"
# studio/native_kernels/int8_gemm: C ABI + static cudart, so one py3-none wheel per platform fits every torch and CUDA 12/13.
I8GEMM_DISTRIBUTION = "unsloth-studio-i8gemm"
I8GEMM_VERSION = "1.0.0"
_I8GEMM_PLATFORMS = {"linux_x86_64": "manylinux_2_28_x86_64", "win_amd64": "win_amd64"}
def int8_gemm_wheel_url(env: dict[str, str] | None) -> str | None:
"""The prebuilt int8 GEMM wheel for an NVIDIA CUDA torch on x86_64 Linux / Windows, else None."""
if env is None or env.get("hip_version") or not env.get("cuda_major"):
return None
platform = _I8GEMM_PLATFORMS.get(str(env.get("platform_tag") or ""))
if platform is None:
return None
return (
f"{UNSLOTH_PREBUILT_RELEASE_BASE_URL}/{UNSLOTH_PREBUILT_RELEASE_TAG}/"
f"unsloth_studio_i8gemm-{I8GEMM_VERSION}-py3-none-{platform}.whl"
)
def mamba_ssm_pure_wheel_url(env: dict[str, str] | None = None) -> str:
"""The extension-free mamba_ssm wheel (the same file for every environment)."""
return (
f"{UNSLOTH_PREBUILT_RELEASE_BASE_URL}/{UNSLOTH_PREBUILT_RELEASE_TAG}/{MAMBA_SSM_PURE_WHEEL}"
)
# Keyed on the torch minor, and exact rather than a floor: a wheel is built against one minor and there is no evidence any future one will load it, which is exactly the assumption that made the upstream wheels stop working here. A new torch minor adds a row only after the workflow has built and smoke-tested it.
_UNSLOTH_PREBUILT_TORCH_MM = frozenset({"2.13", "2.14"})
# The package version published on that tag, which is not the version the upstream branches resolve: the builds are newer because they had to be cut from a source revision that compiles against torch 2.13 at all. flash-attn 2.8.4 in particular exists only as a commit upstream, carrying the c++20 switch from Dao-AILab/flash-attention#2899.
_UNSLOTH_PREBUILT_VERSIONS = {
"flash_attn": "2.8.4",
"causal_conv1d": "1.7.0",
"mamba_ssm": "2.3.2.post1",
}
# platform_tag -> (cxx11abi field, published interpreters or None for any). The Windows cu130 torch also reports cxx11abi True. Only what the release actually carries: torch 2.13 / 2.14 are published for cp313 GIL builds on every platform (the workflow can build cp311 / cp312 cells, but none has been published, and a URL for one is a 404 in front of the fallback).
_UNSLOTH_PREBUILT_PLATFORMS: dict[str, tuple[str, frozenset[str] | None]] = {
"linux_x86_64": ("TRUE", frozenset({"cp313"})),
"win_amd64": ("TRUE", frozenset({"cp313"})),
"linux_aarch64": ("TRUE", frozenset({"cp313"})),
"win_arm64": ("TRUE", frozenset({"cp313"})),
}
# (platform, torch minor) cells outside _UNSLOTH_PREBUILT_TORCH_MM, with their interpreters. Upstream's torch2.10 wheels (and their 2.11 / 2.12 reuse above) have no Windows asset, so win_amd64 torch 2.10, 2.11 and 2.12 are ours; an existing install keeps its minor (a fresh one takes 2.13 on cp313), hence three interpreters.
_UNSLOTH_PREBUILT_EXTRA_CELLS: dict[tuple[str, str], frozenset[str]] = {
("win_amd64", "2.10"): frozenset({"cp311", "cp312", "cp313"}),
("win_amd64", "2.11"): frozenset({"cp311", "cp312", "cp313"}),
("win_amd64", "2.12"): frozenset({"cp311", "cp312", "cp313"}),
("linux_x86_64", "2.10"): frozenset({"cp311", "cp312", "cp313"}),
("linux_x86_64", "2.11"): frozenset({"cp311", "cp312", "cp313"}),
("linux_x86_64", "2.12"): frozenset({"cp311", "cp312", "cp313"}),
("linux_aarch64", "2.10"): frozenset({"cp311", "cp312", "cp313"}),
("linux_aarch64", "2.11"): frozenset({"cp311", "cp312", "cp313"}),
("linux_aarch64", "2.12"): frozenset({"cp311", "cp312", "cp313"}),
}
# Extra cells carrying only some packages: on Linux torch 2.10 to 2.12 ours replace upstream
# causal-conv1d and mamba-ssm; upstream flash-attn 2.8.1 is smaller than ours, so it stays upstream.
_UNSLOTH_PREBUILT_EXTRA_CELL_PREFIXES: dict[str, frozenset[str]] = {
"linux_x86_64": frozenset({"causal_conv1d", "mamba_ssm"}),
"linux_aarch64": frozenset({"causal_conv1d", "mamba_ssm"}),
}
# Windows on ARM has one CUDA torch, NVIDIA's 2.14.0+cu134 (CUDA 13.4, the first with a Windows ARM64 nvcc), and NVIDIA publishes flash-attn for it, so only these two are ours there.
_UNSLOTH_WIN_ARM64_PREFIXES = frozenset({"causal_conv1d", "mamba_ssm"})
_WIN_ARM64_TORCH_MM = "2.14"
_WIN_ARM64_MIN_CUDA = (13, 4)
def _cuda_at_least(env: dict[str, str], floor: tuple[int, int]) -> bool:
try:
major, minor = (int(part) for part in str(env.get("cuda_version") or "").split(".")[:2])
except ValueError:
return False
return (major, minor) >= floor
# NVIDIA's flash-attn for Windows on ARM, built for the torch 2.14.0+cu134 the WoA installer takes. Not ours to sign: each file is pinned by GitHub's asset sha256 via a #sha256= fragment, which uv and pip both enforce.
NVIDIA_WOA_FLASH_ATTN_RELEASE_URL = (
"https://github.com/NVIDIA/pytorch-windows-ci/releases/download/Flash-Attention-for-WoA"
)
NVIDIA_WOA_FLASH_ATTN_VERSION = "2.8.4"
NVIDIA_WOA_FLASH_ATTN_TORCH_MM = "2.14"
NVIDIA_WOA_FLASH_ATTN_SHA256 = {
"cp311": "1995cf916142eeadf8474ec992b2215d3b0319dfbf0b2b57b627f1c3d2f907e4",
"cp312": "4be12d62df9e5adafc1be7451b9b3b2ea335d43ebd1b8288e642097144236de2",
"cp313": "54d1c98df04b133d227d5414a9d6d9d668e4b049246b96ecfd811b8272a9d926",
"cp314": "b016989f1d30a01edc9fff9ba5643170174c27cc12968fdaa33ca1c055eb17aa",
"cp314t": "c5269dc146c61a35e95df34aea81f35b85d7449d912325e4af00640f63cfcd5a",
}
def is_windows_wheel_env(env: dict[str, str] | None) -> bool:
"""True for a Windows env, where a kernel comes from a listed wheel or not at all."""
return bool(env) and str(env.get("platform_tag") or "").startswith("win_")
def nvidia_woa_flash_attn_wheel_url(env: dict[str, str] | None) -> str | None:
"""NVIDIA's win_arm64 flash-attn for this env, with its pinned #sha256= fragment, else None."""
if env is None or env.get("platform_tag") != "win_arm64":
return None
if env.get("torch_mm") != NVIDIA_WOA_FLASH_ATTN_TORCH_MM or not _cuda_at_least(
env, _WIN_ARM64_MIN_CUDA
):
return None
python_tag = env.get("python_tag") or ""
abi_tag = env.get("abi_tag") or python_tag
digest = NVIDIA_WOA_FLASH_ATTN_SHA256.get(abi_tag)
if not python_tag or digest is None or not abi_tag.startswith(python_tag):
return None
filename = (
f"flash_attn-{NVIDIA_WOA_FLASH_ATTN_VERSION}+cu13torch{NVIDIA_WOA_FLASH_ATTN_TORCH_MM}"
f"-{python_tag}-{abi_tag}-win_arm64.whl"
)
return f"{NVIDIA_WOA_FLASH_ATTN_RELEASE_URL}/{filename}#sha256={digest}"
def unsloth_prebuilt_wheel_url(*, filename_prefix: str, env: dict[str, str] | None) -> str | None:
"""Our own prebuilt wheel for this environment, or None to leave resolution unchanged.
Every gate here is narrower than it strictly has to be, because the cost of the two answers is not symmetric: returning None costs a source build the user was already facing, and returning a URL for a combination we did not publish costs a 404 and the same source build with a misleading log line in front of it. So it answers only for the exact cells the workflow builds, and the torch minor, CUDA major, ABI, interpreter and platform must all match (see _UNSLOTH_PREBUILT_PLATFORMS); macOS keeps whatever behaviour it has today.
"""
if env is None:
return None
platform_tag = str(env.get("platform_tag") or "")
extra_pythons = _UNSLOTH_PREBUILT_EXTRA_CELLS.get((platform_tag, str(env.get("torch_mm"))))
if env.get("torch_mm") not in _UNSLOTH_PREBUILT_TORCH_MM and extra_pythons is None:
return None
# cu13 only. The workflow builds against the CUDA 13 toolkit and nothing else.
if env.get("cuda_major") != "13":
return None
platform_spec = _UNSLOTH_PREBUILT_PLATFORMS.get(platform_tag)
if platform_spec is None:
return None
cxx11abi, published_pythons = platform_spec
if extra_pythons is not None:
extra_prefixes = _UNSLOTH_PREBUILT_EXTRA_CELL_PREFIXES.get(platform_tag)
if extra_prefixes is not None and filename_prefix not in extra_prefixes:
return None
published_pythons = extra_pythons
if env.get("platform_tag") == "win_arm64" and (
filename_prefix not in _UNSLOTH_WIN_ARM64_PREFIXES
or env.get("torch_mm") != _WIN_ARM64_TORCH_MM
or not _cuda_at_least(env, _WIN_ARM64_MIN_CUDA)
):
return None
# Every Linux torch pip wheel from 2.7 on is built with _GLIBCXX_USE_CXX11_ABI=1, so there is no abiFALSE variant to publish. A torch built otherwise -- a source build, an NGC image -- is not something these wheels can serve.
if env.get("cxx11abi") != cxx11abi:
return None
python_tag = env.get("python_tag")
if not python_tag:
return None
if published_pythons is not None:
if python_tag not in published_pythons:
return None
if (env.get("abi_tag") or python_tag) != python_tag:
return None
package_version = _UNSLOTH_PREBUILT_VERSIONS.get(filename_prefix)
if package_version is None:
return None
filename = (
f"{filename_prefix}-{package_version}"
f"+cu{env['cuda_major']}torch{env['torch_mm']}"
f"cxx11abi{env['cxx11abi']}-{python_tag}-{python_tag}"
f"-{env['platform_tag']}.whl"
)
return f"{UNSLOTH_PREBUILT_RELEASE_BASE_URL}/{UNSLOTH_PREBUILT_RELEASE_TAG}/{filename}"
# Cells the pinned releases (causal-conv1d v1.6.1.post4, mamba-ssm v2.3.1) publish for cp310-cp313;
# anything else (CUDA 13 before torch 2.9, aarch64 before 2.7, abiFALSE torch after 2.6) would 404
# ahead of the source fallback, so it resolves to nothing.
_UPSTREAM_SSM_PINS = {
"causal_conv1d": CAUSAL_CONV1D_PACKAGE_VERSION,
"mamba_ssm": MAMBA_SSM_PACKAGE_VERSION,
}
_UPSTREAM_SSM_CELLS: dict[tuple[str, str, str], frozenset[str]] = {
("linux_x86_64", "11", "FALSE"): frozenset({"2.6"}),
("linux_x86_64", "11", "TRUE"): frozenset({"2.6", "2.7"}),
("linux_x86_64", "12", "FALSE"): frozenset({"2.6"}),
("linux_x86_64", "12", "TRUE"): frozenset({"2.6", "2.7", "2.8", "2.9", "2.10"}),
("linux_x86_64", "13", "TRUE"): frozenset({"2.9", "2.10"}),
("linux_aarch64", "12", "TRUE"): frozenset({"2.7", "2.8", "2.9", "2.10"}),
("linux_aarch64", "13", "TRUE"): frozenset({"2.9", "2.10"}),
}
_UPSTREAM_SSM_PYTHONS = frozenset({"cp310", "cp311", "cp312", "cp313"})
def _upstream_ssm_cell_published(filename_prefix: str, package_version: str, env: dict) -> bool:
if _UPSTREAM_SSM_PINS.get(filename_prefix) != package_version:
return True # not a pinned release this table describes: unchanged
torch_mm = prebuilt_wheel_torch_mm(str(env.get("torch_mm")))
cell = (str(env.get("platform_tag")), str(env.get("cuda_major")), str(env.get("cxx11abi")))
python_tag = env.get("python_tag")
return (
torch_mm in _UPSTREAM_SSM_CELLS.get(cell, frozenset())
and python_tag in _UPSTREAM_SSM_PYTHONS
and (env.get("abi_tag") or python_tag) == python_tag
)
# The newest torch the pinned causal-conv1d 1.6.1 / mamba-ssm 2.3.1 compile against: torch 2.13
# raised its headers to C++20 and both build at C++17 (the prebuilt workflow moved to
# causal-conv1d 1.7.0 and patches mamba-ssm for it, see .github/scripts/patch_mamba_cxx20.py).
PINNED_SOURCE_BUILD_MAX_TORCH = (2, 12)
def pinned_source_build_supported(env: dict[str, str] | None) -> bool:
"""Whether a source build of the pinned causal-conv1d / mamba-ssm (or their upstream wheels)
can work with this torch; from torch 2.13 on only our prebuilt wheels can."""
try:
major, minor = (int(part) for part in str((env or {}).get("torch_mm") or "").split(".")[:2])
except ValueError:
return True # unknown: leave the decision to the build, as before
return (major, minor) <= PINNED_SOURCE_BUILD_MAX_TORCH
def direct_wheel_url(
*,
filename_prefix: str,
package_version: str,
release_tag: str,
release_base_url: str,
env: dict[str, str] | None,
) -> str | None:
if env is None or not env.get("cuda_major"):
return None
# Checked before the upstream filename is built, not after: for torch 2.13+ the upstream URL this would otherwise return names an asset that has never existed, so there is nothing to fall back to and no reason to prefer it. Every caller -- causal-conv1d and mamba-ssm on both the training and the inference path -- picks this up without changing its own arguments, which is why the override lives here rather than at each call site.
ours = unsloth_prebuilt_wheel_url(filename_prefix = filename_prefix, env = env)
if ours is not None:
return ours
# No upstream release has a Windows asset, nor one for torch 2.13 or later (see above).
if is_windows_wheel_env(env) or not pinned_source_build_supported(env):
return None
if not _upstream_ssm_cell_published(filename_prefix, package_version, env):
return None
filename = (
f"{filename_prefix}-{package_version}"
f"+cu{env['cuda_major']}torch{prebuilt_wheel_torch_mm(env['torch_mm'])}"
f"cxx11abi{env['cxx11abi']}-{env['python_tag']}-{env['python_tag']}"
f"-{env['platform_tag']}.whl"
)
return f"{release_base_url}/{release_tag}/{filename}"
# xformers/_C links one exact (torch, CUDA) pair; a mismatch silently drops attention. Key on cpp_lib.json torch, not cuda; rows never interpolated.
# ── xFormers ──────────────────────────────────────────────────────────────────
PYTORCH_WHEEL_INDEX_BASE_URL = "https://download.pytorch.org/whl"
def pytorch_wheel_index_base_url() -> str:
"""Where torch-family wheels are fetched from: ``UNSLOTH_PYTORCH_MIRROR`` when set. Read per call rather than frozen at import: this module is imported early, and the mirror is the one setting an air-gapped deployment has. The whole installer stack already honours it (``install_python_stack._PYTORCH_WHL_BASE``, install.sh, setup.ps1), so a direct-URL install that hard-coded download.pytorch.org was the one path that could not reach a mirror-only host, failing the explicit xFormers request and dropping the user back to native attention."""
return (os.environ.get("UNSLOTH_PYTORCH_MIRROR") or PYTORCH_WHEEL_INDEX_BASE_URL).rstrip("/")
_XFORMERS_WHEEL_VERSIONS: dict[str, dict[str, str]] = {
# torch 2.7.0 is deliberately absent: it predates the stable-ABI switch, so it ships one wheel per interpreter and stops at cp312, while Unsloth's default interpreter is 3.13. Supporting it would mean a per-interpreter gate here and a second one in install.ps1, for a torch that resolves to nothing on the default install anyway (xFormers 0.0.30).
"2.7.1": {"cu126": "0.0.31.post1", "cu128": "0.0.31.post1"},
"2.8.0": {"cu126": "0.0.32.post2", "cu128": "0.0.32.post2", "cu129": "0.0.32.post2"},
"2.9.0": {"cu126": "0.0.33.post1", "cu128": "0.0.33.post1", "cu130": "0.0.33.post1"},
"2.9.1": {"cu126": "0.0.33.post2", "cu128": "0.0.33.post2", "cu130": "0.0.33.post2"},
"2.10.0": {"cu126": "0.0.34", "cu128": "0.0.34", "cu130": "0.0.34"},
# Stable-ABI era: one wheel serves every torch from 2.11 on. The rows stay listed so a future exact-pinned release can displace a single one of them, but they are no longer the only way in: _XFORMERS_STABLE_ABI below covers the patch releases between them.
"2.11.0": {"cu126": "0.0.35", "cu128": "0.0.35", "cu130": "0.0.35"},
"2.12.0": {"cu126": "0.0.35", "cu128": "0.0.35", "cu130": "0.0.35"},
"2.13.0": {"cu126": "0.0.35", "cu128": "0.0.35", "cu130": "0.0.35"},
}
# The stable-ABI floor and what serves it: every torch STRICTLY ABOVE this maps to this release, per CUDA family, with exact rows above still winning. An exact-key table alone refused the patch releases (2.10.1, 2.11.1, 2.12.1), which cannot be enumerated because they ship after this code; 0.0.35 targets 2.10.0 and upstream states later versions stay compatible. Below the floor there is no stable ABI, so an unlisted pair must keep resolving to nothing.
_XFORMERS_STABLE_ABI_FLOOR: tuple[int, ...] = (2, 10, 0)
_XFORMERS_STABLE_ABI_VERSIONS = {"cu126": "0.0.35", "cu128": "0.0.35", "cu130": "0.0.35"}
# The interpreter tag in the wheel FILENAME, which xFormers has changed twice: 0.0.30 and earlier ship one wheel per cpXY (and stop at cp312), 0.0.31..0.0.34 ship a single cp39-abi3 wheel, and 0.0.35 switched to py39-none. That last switch is a PACKAGING change, not an architectural one: 0.0.35's setup.py drops py_limited_api=True and force-tags the wheel through a custom bdist_wheel, since the extension is loaded by torch.ops.load_library and its _C.so defines no PyInit. The wheel still carries a per-CUDA _C.pyd; it just dropped the bundled flash_attn_3 kernels, the whole 103 MB -> 2.6 MB difference. Ranges, not an open-ended floor: an unknown release resolves to nothing until somebody checks the real filename.
_XFORMERS_FILENAME_PYTHON_TAGS: tuple[tuple[tuple[int, ...], tuple[int, ...], str], ...] = (
((0, 0, 31), (0, 0, 34), "cp39-abi3"),
((0, 0, 35), (0, 0, 35), "py39-none"),
)
# platform_tag from wheel_platform_tag() -> the leaf in the wheel filename. aarch64 and macOS are absent because download.pytorch.org publishes no xFormers wheel for them.
_XFORMERS_PLATFORM_LEAVES = {
"linux_x86_64": "manylinux_2_28_x86_64",
"win_amd64": "win_amd64",
}
def _xformers_version_tuple(version: str) -> tuple[int, ...]:
"""'0.0.33.post1' -> (0, 0, 33). Stops at the first non-numeric component."""
parts: list[int] = []
for chunk in str(version).split("."):
digits = re.sub(r"[^0-9].*", "", chunk)
if not digits:
break
parts.append(int(digits))
return tuple(parts)
def xformers_filename_python_tag(version: str) -> str | None:
"""The interpreter tag in an xFormers wheel filename, or None for an unknown release."""
parsed = _xformers_version_tuple(version)
if not parsed:
return None
for low, high, tag in _XFORMERS_FILENAME_PYTHON_TAGS:
if low <= parsed <= high:
return tag
return None
def xformers_cuda_family(cuda_version: str | None) -> str | None:
"""torch.version.cuda -> the download.pytorch.org index leaf ('12.8' -> 'cu128'). None for a ROCm / CPU / XPU torch, which has no xFormers wheel anywhere."""
if not cuda_version:
return None
parts = str(cuda_version).strip().split(".")
try:
major = int(re.sub(r"[^0-9].*", "", parts[0]))
minor = int(re.sub(r"[^0-9].*", "", parts[1])) if len(parts) > 1 else 0
except (IndexError, ValueError):
return None
return f"cu{major}{minor}"
def xformers_wheel_version(torch_version: str | None, cuda_family: str | None) -> str | None:
"""The xFormers release for this (torch, CUDA family), else None. An exact row wins; failing that, any release above the stable-ABI floor resolves to the wheel that serves that whole era, since the exact table cannot list patch releases published after this code ships and refusing them left supported builds (2.11.1, 2.12.1) with no xFormers at all."""
if not torch_version or not cuda_family:
return None
# '2.10.0+cu130' -> '2.10.0'. A dev/rc torch has no wheel and must miss the table.
release = str(torch_version).split("+", 1)[0].strip()
exact = _XFORMERS_WHEEL_VERSIONS.get(release, {}).get(cuda_family)
if exact is not None:
return exact
# A dev/nightly/rc suffix ('2.11.0.dev20260101') is not a released torch, so it stays out: _xformers_version_tuple stops at the first non-numeric chunk, which would read it as the release itself.
if not re.fullmatch(r"[0-9]+(?:\.[0-9]+)*", release):
return None
if _xformers_version_tuple(release) > _XFORMERS_STABLE_ABI_FLOOR:
return _XFORMERS_STABLE_ABI_VERSIONS.get(cuda_family)
return None
def xformers_wheel_url(env: dict[str, str] | None) -> str | None:
"""Direct URL of the xFormers wheel matching ``env``'s torch build, else None. None means "no matched wheel exists" and callers must install nothing rather than fall back to an unpinned resolve, since an unpinned install is what produces the mismatched extension in the first place."""
if env is None:
return None
platform_leaf = _XFORMERS_PLATFORM_LEAVES.get(str(env.get("platform_tag") or ""))
if platform_leaf is None:
return None
family = xformers_cuda_family(env.get("cuda_version"))
version = xformers_wheel_version(env.get("torch_version"), family)
if version is None:
return None
python_tag = xformers_filename_python_tag(version)
if python_tag is None:
return None
return join_wheel_url(
pytorch_wheel_index_base_url(),
f"{family}/xformers-{version}-{python_tag}-{platform_leaf}.whl",
)
def xformers_torch_requirement_unmet() -> tuple[str, str, str] | None:
"""(xformers version, unmet torch specifier, torch version) from metadata, or None if unmet cannot be shown."""
try:
from importlib.metadata import requires, version
from packaging.requirements import Requirement
from packaging.version import Version
xformers_version = version("xformers")
torch_version = version("torch")
installed = Version(torch_version)
declared = requires("xformers") or []
except Exception: # noqa: BLE001 -- either package absent, or no packaging
return None
for line in declared:
try:
requirement = Requirement(line)
if requirement.name.lower() != "torch":
continue
if requirement.marker is not None and not requirement.marker.evaluate({"extra": ""}):
continue
except Exception: # noqa: BLE001 -- a line packaging cannot parse is not a verdict
continue
# Local tags are ignored as pip ignores them, so "torch==2.6.0" accepts 2.6.0+cu124.
if not requirement.specifier.contains(installed, prereleases = True):
return xformers_version, str(requirement.specifier), torch_version
return None
def join_wheel_url(base: str, path: str) -> str:
"""``base`` + ``path``, with any ?query / #fragment kept at the end. UNSLOTH_PYTORCH_MIRROR is allowed to authenticate by query string (``https://mirror/whl?token=abc``), and appending after the query put the wheel path INSIDE the token value, leaving the request path at /whl and the token unusable. The tokenized private mirror this setting exists for was the one shape that could not resolve a wheel."""
cut = min([i for i in (base.find("?"), base.find("#")) if i >= 0], default = -1)
if cut < 0:
return f"{base.rstrip('/')}/{path}"
return f"{base[:cut].rstrip('/')}/{path}{base[cut:]}"
def redact_url_credentials(url: str) -> str:
"""A URL safe to log: no userinfo, no query, no fragment. UNSLOTH_PYTORCH_MIRROR is allowed to be a private index, and people put credentials in it (``https://user:token@mirror/whl`` or ``...?token=``). The wheel URL built from it is handed to pip AND printed, so without this the secret lands in the backend log the first time Unsloth installs (or fails to install) xFormers. Same rule as the installer's Remove-IndexUrlCredentials, so both sides redact identically."""
separator = url.find("://")
if separator < 0:
return url
scheme, rest = url[:separator], url[separator + 3 :]
cut = min([i for i in (rest.find("?"), rest.find("#")) if i >= 0], default = -1)
if cut >= 0:
rest = rest[:cut]
slash = rest.find("/")
authority, path = (rest[:slash], rest[slash:]) if slash >= 0 else (rest, "")
at = authority.rfind("@")
if at >= 0:
authority = authority[at + 1 :]
return f"{scheme}://{authority}{path}"
def flash_attn_package_version(torch_mm: str) -> str | None:
if torch_mm == "2.10":
# Newest flash-attn release still carrying the full torch2.10 asset matrix. Do not bump to "the latest release": v2.8.3 publishes only cu13/cp312 for torch2.10 and v2.8.3.post1 dropped every torch2.10 asset, 404ing most users into a source build. The full matrix is cu12 + cu13, cp312 + cp313, x86_64 + aarch64, and post1's newest tag is torch2.9, which will not load here at all.
return "2.8.1"
try:
major, minor = (int(part) for part in torch_mm.split(".", 1))
except ValueError:
return None
if major == 2 and 4 <= minor <= 9:
return "2.8.3"
return None
def flash_attn_wheel_url(env: dict[str, str] | None) -> str | None:
if env is None:
return None
# flash-attn does not reach direct_wheel_url on torch 2.13+: flash_attn_package_version returns None there and this function bails before the URL is ever built, so the override has to be asked here too. It is the same predicate and the same table; only the entry point differs.
ours = unsloth_prebuilt_wheel_url(filename_prefix = "flash_attn", env = env)
if ours is not None:
return ours
if is_windows_wheel_env(env):
return nvidia_woa_flash_attn_wheel_url(env)
package_version = flash_attn_package_version(prebuilt_wheel_torch_mm(env["torch_mm"]))
if package_version is None:
return None
return direct_wheel_url(
filename_prefix = "flash_attn",
package_version = package_version,
release_tag = f"v{package_version}",
release_base_url = FLASH_ATTN_RELEASE_BASE_URL,
env = env,
)
_WHEEL_FILENAME_FIELD_RE = re.compile(r"[A-Za-z0-9._+!]+")
# Each picks the directory uv discovers its project config from; --project would override it.
_UV_PROJECT_DIR_ENV = ("UV_PROJECT", "UV_WORKING_DIR", "UV_WORKING_DIRECTORY")
def _pyproject_has_uv_table(path: str) -> bool:
"""Whether a pyproject.toml has a [tool.uv] table; True when unreadable, so its config is kept."""
try:
# novermin -- 3.11; the ImportError fallback below is the guard, which vermin cannot see.
import tomllib # novermin
except ImportError: # Python < 3.11: no parser, stay out of the way
return True
try:
with open(path, "rb") as fh:
data = tomllib.load(fh)
except (OSError, ValueError):
return True
tool = data.get("tool")
return isinstance(tool, dict) and "uv" in tool
def _uv_project_config_found() -> bool:
"""Whether uv would find a project config from the cwd, which --project elsewhere drops."""
try:
directory = os.getcwd()
except OSError:
return True
while True:
if os.path.isfile(os.path.join(directory, "uv.toml")):
return True
pyproject = os.path.join(directory, "pyproject.toml")
if os.path.isfile(pyproject) and _pyproject_has_uv_table(pyproject):
return True
parent = os.path.dirname(directory)
if parent == directory:
return False
directory = parent
# uv's boolean environment values; anything else counts as set, which only skips the shortcut.
_UV_ENV_FALSE = frozenset({"", "0", "false", "f", "no", "n", "off"})
def _uv_env_flag_set(name: str) -> bool:
return os.environ.get(name, "").strip().lower() not in _UV_ENV_FALSE
def _uv_static_metadata_config(wheel_url: str, config_dir: str) -> bool:
"""Write a uv.toml giving uv the wheel's metadata, so a rangeless GitHub asset downloads once
(astral-sh/uv#18998); --no-deps makes the empty requires-dist exact. True if written."""
if os.environ.get("UV_CONFIG_FILE") or _uv_env_flag_set("UV_NO_CONFIG"):
return False
if any(os.environ.get(name) for name in _UV_PROJECT_DIR_ENV) or _uv_project_config_found():
return False
filename = urllib.parse.unquote(urllib.parse.urlsplit(wheel_url).path.rsplit("/", 1)[-1])
fields = filename[: -len(".whl")].split("-") if filename.endswith(".whl") else []
if len(fields) not in (5, 6) or not all(
_WHEEL_FILENAME_FIELD_RE.fullmatch(f) for f in fields[:2]
):
return False
name, version = fields[0].replace("_", "-").lower(), fields[1].lower()
with open(os.path.join(config_dir, "uv.toml"), "w", encoding = "utf-8") as fh:
fh.write(
"[[dependency-metadata]]\n"
f'name = "{name}"\n'
f'version = "{version}"\n'
"requires-dist = []\n"
)
return True
_UV_OFFLINE_TRUE_VALUES = frozenset({"1", "true", "t", "yes", "y", "on"})
_HF_OFFLINE_TRUE_VALUES = frozenset({"1", "true", "yes", "on"})
def uv_offline() -> bool:
"""UV_OFFLINE, the operator's no-network switch for installs, in uv's boolish spellings."""
return os.environ.get("UV_OFFLINE", "").strip().lower() in _UV_OFFLINE_TRUE_VALUES
# Set (to "1") while Studio itself forced HF offline only because the Hugging Face endpoint was
# unreachable (export's _offline_window_if_unreachable), and restored when that window closes.
# HF_HUB_OFFLINE / TRANSFORMERS_OFFLINE then say nothing about GitHub or PyPI, so a kernel install
# may still reach them; only UV_OFFLINE keeps it off the network. Children inherit it.
HF_OFFLINE_AUTO_ENV = "_UNSLOTH_HF_OFFLINE_AUTO"
def hf_offline_auto_set() -> bool:
"""True while HF offline was set by Studio for an unreachable Hub, not by the operator."""
return os.environ.get(HF_OFFLINE_AUTO_ENV, "") == "1"
def package_installs_offline_env() -> bool:
"""The environment half of utils.utils.package_installs_offline, for callers that cannot import
the backend (`unsloth install-kernels` runs under --no-deps): HF_HUB_OFFLINE,
TRANSFORMERS_OFFLINE or UV_OFFLINE. While HF offline was only auto-set for an unreachable Hub
(hf_offline_auto_set), only UV_OFFLINE counts."""
if hf_offline_auto_set():
return uv_offline()
return uv_offline() or any(
os.environ.get(name, "").strip().lower() in _HF_OFFLINE_TRUE_VALUES
for name in ("HF_HUB_OFFLINE", "TRANSFORMERS_OFFLINE")
)
def install_wheel(
wheel_url: str,
*,
python_executable: str,
use_uv: bool,
uv_needs_system: bool = False,
reinstall: bool = False,
run: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
) -> list[tuple[str, subprocess.CompletedProcess[str]]]:
attempts: list[tuple[str, subprocess.CompletedProcess[str]]] = []
if use_uv and shutil.which("uv"):
uv_cmd = ["uv", "pip", "install"]
if uv_needs_system:
uv_cmd.append("--system")
uv_cmd.extend(["--python", python_executable, "--no-deps"])
# Without it an installed same-version build (another CUDA, or a broken copy) is kept.
if reinstall:
uv_cmd.append("--reinstall")
uv_cmd.append(wheel_url)
config_dir = None
try:
config_dir = tempfile.mkdtemp(prefix = "unsloth-uv-")
# --project, not cwd: relative UV_CACHE_DIR etc. still resolve here; uv pip reads only config from it.
if _uv_static_metadata_config(wheel_url, config_dir):
uv_cmd[1:1] = ["--project", config_dir]
except OSError:
pass # Optional: an unwritable temp dir must not stop the plain uv install.
try:
result = run(
uv_cmd,
stdout = subprocess.PIPE,
stderr = subprocess.STDOUT,
text = True,
encoding = "utf-8",
errors = "replace",
env = child_env_without_native_path_secret(),
)
finally:
if config_dir:
shutil.rmtree(config_dir, ignore_errors = True)
attempts.append(("uv", result))
if result.returncode == 0:
return attempts
# uv refused the network under UV_OFFLINE; pip has no such switch and would reach it.
if uv_offline():
return attempts
pip_cmd = [python_executable, "-m", "pip", "install", "--no-deps"]
if reinstall:
pip_cmd.append("--force-reinstall")
pip_cmd.append(wheel_url)
result = run(
pip_cmd,
stdout = subprocess.PIPE,
stderr = subprocess.STDOUT,
text = True,
encoding = "utf-8",
errors = "replace",
# Make the Python child emit the UTF-8 we decode above.
env = utf8_child_env(child_env_without_native_path_secret()),
)
attempts.append(("pip", result))
return attempts
def url_exists(url: str) -> bool | None:
"""True if reachable, False on a 404, None when it cannot be checked: a refusal is no proof the wheel is unpublished."""
try:
request = urllib.request.Request(url, method = "HEAD")
with urllib.request.urlopen(request, timeout = 10):
return True
except urllib.error.HTTPError as exc:
if exc.code == 404:
return False
reason = f"HTTP {exc.code}"
except (OSError, http.client.HTTPException) as exc:
reason = str(exc)
shown = redact_url_credentials(url)
if shown != url:
# The error text can echo the userinfo (urllib reads `user:token@host` as a port).
reason = reason if reason.startswith("HTTP ") else "unreachable"
_logger.warning(
"url_exists(%s): %s; could not check prebuilt wheel availability", shown, reason
)
return None