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
"""Only desktop launches on AMD hosts copy allowlisted ROCm vars that are absent here from the login
shell; every other launch reads no shell"""
from __future__ import annotations
import logging
import os
import re
import shlex
import signal
import subprocess
import sys
import tempfile
logger = logging.getLogger(__name__)
DISABLE_ENV_VAR = "UNSLOTH_DISABLE_SHELL_ENV_IMPORT"
# Set by src-tauri on every CLI child it owns (process.rs, DESKTOP_MANAGED_ENV).
DESKTOP_MANAGED_ENV = "UNSLOTH_DESKTOP_MANAGED"
# The CLI's guard ran in a different environment, so its verdict is not reused here.
ROCM_INSTALLED_ARCH_ENV = "UNSLOTH_ROCM_INSTALLED_ARCH"
HSA_OVERRIDE_ENV = "HSA_OVERRIDE_GFX_VERSION"
# AMD/ROCm only: a wider list would change a GUI launch on someone else's stack.
ROCM_SHELL_ENV_ALLOWLIST: tuple[str, ...] = (
"HSA_OVERRIDE_GFX_VERSION",
"PYTORCH_ROCM_ARCH",
"AMDGPU_TARGETS",
"GPU_TARGETS",
"ROCM_PATH",
"ROCM_HOME",
"HIP_PATH",
"HIP_PLATFORM",
# CK was being attempted on an arch it was not built for (#9926).
"USE_CK",
"TORCH_BLAS_PREFER_HIPBLASLT",
"MIOPEN_USER_DB_PATH",
"MIOPEN_CUSTOM_CACHE_DIR",
"MIOPEN_FIND_MODE",
# Preserve shell overrides, including an explicit opt-out (0).
"MIOPEN_SEARCH_CUTOFF",
"HIP_VISIBLE_DEVICES",
"ROCR_VISIBLE_DEVICES",
"GPU_DEVICE_ORDINAL",
# DXG_DETECTION: main.py sets it for WSL, a host that set it by hand wins.
"HSA_ENABLE_SDMA",
"HSA_ENABLE_DXG_DETECTION",
"HSA_XNACK",
"HSA_FORCE_FINE_GRAIN_PCIE",
"AMD_SERIALIZE_KERNEL",
"GPU_MAX_HW_QUEUES",
)
# Not HSA_TOOLS_LIB: HSA dlopens it, so it loads a library rather than tuning one.
# Exception list, so a renamed bash/zsh still gets the unsloth#12678 probe.
_NON_POSIX_SHELLS = frozenset(
{"fish", "nu", "nushell", "csh", "tcsh", "xonsh", "elvish", "pwsh", "ion", "murex"}
)
def probe_command(shell: str, command: str) -> str:
"""Unsets RCS to skip the exit-time history save; dash exits on a readonly unset, hence the subshell."""
if os.path.basename(shell) in _NON_POSIX_SHELLS:
return command
return (
"if [ -n \"${ZSH_VERSION-}\" ]; then eval 'unsetopt RCS' 2>/dev/null || :; fi; "
f"(unset HISTFILE) 2>/dev/null && unset HISTFILE; exec {command}"
)
# NVIDIA's open kernel module registers KFD nodes too (4318), hence the check.
_AMD_VENDOR_ID = "4098"
def host_has_amd_gpu() -> bool:
"""Reads the KFD topology rather than torch, because this runs before torch is imported."""
if not sys.platform.startswith("linux"):
return False
try:
if not os.path.exists("/dev/kfd"):
return False
nodes = "/sys/class/kfd/kfd/topology/nodes"
for entry in sorted(os.listdir(nodes)):
path = os.path.join(nodes, entry, "properties")
try:
with open(path, "r", encoding = "utf-8", errors = "replace") as handle:
text = handle.read()
except OSError:
continue
if _node_is_an_amd_gpu(text):
return True
except Exception:
return False
return False
def _node_is_an_amd_gpu(properties: str) -> bool:
"""Whether one KFD node's ``properties`` file describes an AMD GPU."""
fields = {}
for line in properties.splitlines():
key, _, value = line.partition(" ")
fields[key] = value.strip()
try:
if int(fields.get("gfx_target_version", "0")) <= 0:
return False
except ValueError:
return False
return fields.get("vendor_id") == _AMD_VENDOR_ID
def read_login_shell_env(shell: "str | None" = None, timeout: float = 15.0) -> dict:
"""Env goes to a file: newlines in values break line parsing; background rc jobs can hold pipes."""
shell = shell or os.environ.get("SHELL") or "/bin/sh"
with tempfile.TemporaryDirectory(prefix = "unsloth-shell-env-") as work:
target = os.path.join(work, "env")
command = f"env -0 > {shlex.quote(target)}"
probe = probe_command(shell, command)
returncode = _run_login_shell(shell, probe, timeout)
# A non-POSIX shell missing from the list rejects the probe; never after a timeout.
if returncode not in (0, None) and probe != command:
returncode = _run_login_shell(shell, command, timeout)
if returncode != 0:
logger.debug("login shell exited %s", returncode)
return {}
try:
with open(target, "rb") as handle:
raw = handle.read()
except OSError as error:
logger.debug("login shell wrote no environment: %s", error)
return {}
out: dict = {}
# surrogateescape, as os.environ does: `replace` corrupts a path.
for record in raw.decode("utf-8", "surrogateescape").split("\0"):
name, sep, value = record.partition("=")
if sep and name:
out[name] = value
return out
def _run_login_shell(shell: str, command: str, timeout: float) -> "int | None":
"""``shell -ilc command``'s exit status; ``None`` if it could not start or timed out."""
try:
process = subprocess.Popen(
[shell, "-ilc", command],
stdin = subprocess.DEVNULL,
stdout = subprocess.DEVNULL,
stderr = subprocess.DEVNULL,
# Oh My Zsh's auto-update prompt can block the shell forever.
env = {**os.environ, "DISABLE_AUTO_UPDATE": "true"},
# Its own group, so the cleanup below takes the whole shell.
start_new_session = True,
)
except Exception as error:
logger.debug("login shell environment unavailable: %s", error)
return None
# pgid == pid, read before the wait reaps it: getpgid then raises.
group = process.pid
try:
return process.wait(timeout = timeout)
except Exception as error:
logger.debug("login shell did not finish: %s", error)
return None
finally:
# Every path: a clean exit still leaves an rc's agent running.
_terminate_group(group, process)
def _terminate_group(group: int, process) -> None:
"""Kill the shell's session and anything left in it. Never raises."""
try:
os.killpg(group, signal.SIGKILL)
except Exception:
pass
try:
process.wait(timeout = 5)
except Exception:
pass
def select_missing_vars(
environ,
shell_env,
allowlist = ROCM_SHELL_ENV_ALLOWLIST,
) -> dict:
"""Test membership, not truthiness: an exported empty ROCR_VISIBLE_DEVICES= hides every agent."""
out: dict = {}
for name in allowlist:
if name in environ:
continue
if name in shell_env and isinstance(shell_env[name], str):
out[name] = shell_env[name]
return out
def import_rocm_env_from_login_shell(
environ = None,
shell = None,
timeout: float = 15.0,
) -> dict:
"""Fill in the ROCm variables a desktop launch dropped. Returns what it set."""
environ = os.environ if environ is None else environ
if str(environ.get(DISABLE_ENV_VAR, "")).strip() == "1":
return {}
# Not a desktop launch: nothing was lost, so nothing is read.
if str(environ.get(DESKTOP_MANAGED_ENV, "")).strip() != "1":
return {}
if not sys.platform.startswith("linux"):
return {}
if not host_has_amd_gpu():
return {}
if all(name in environ for name in ROCM_SHELL_ENV_ALLOWLIST):
return {}
imported = select_missing_vars(environ, read_login_shell_env(shell, timeout))
if HSA_OVERRIDE_ENV in imported and override_contradicts_install(
imported[HSA_OVERRIDE_ENV], environ.get(ROCM_INSTALLED_ARCH_ENV)
):
logger.info(
"Not importing %s=%s from the login shell: this install carries %s kernels "
"only (#7331).",
HSA_OVERRIDE_ENV,
imported[HSA_OVERRIDE_ENV],
environ.get(ROCM_INSTALLED_ARCH_ENV),
)
del imported[HSA_OVERRIDE_ENV]
for name, value in imported.items():
environ[name] = value
if imported:
logger.info(
"Imported ROCm environment from the login shell (desktop launches do "
"not inherit it): %s",
", ".join(sorted(imported)),
)
return imported
def override_gfx_arch(value):
"""Kept in step with _hsa_override_gfx_arch in unsloth_cli and install.sh; a test checks parity."""
if not isinstance(value, str) or not value:
return None
# [0-9] rather than str.isdigit()/\d, both of which accept non-ASCII digits.
if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", value.strip()):
return None
major, minor, step = (int(part) for part in value.strip().split("."))
# Steppings are a single hex nibble; anything wider is not a real target.
if not (0 <= step <= 15) or major <= 0 or minor > 9:
return None
return f"gfx{major}{minor}{step:x}"
def override_contradicts_install(value, installed_arch) -> bool:
"""False for an unparsable value, matching the CLI guard that leaves such an override alone."""
if not installed_arch:
return False
named = override_gfx_arch(value)
return named is not None and named != installed_arch