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>).
If CUDA_VISIBLE_DEVICES is already set in the environment (e.g.,
by the user or a wrapper script), only consider those GPUs when
selecting devices for llama-server. nvidia-smi reports all physical
GPUs regardless of CUDA_VISIBLE_DEVICES, so we filter its output
to match the allowed set.
Without this, the GPU selector could pick a GPU outside the user's
allowed set, overriding their restriction.
Automatically select the best GPU(s) for a GGUF model based on
file size and available VRAM, instead of relying on hardcoded
-ngl -1 or letting llama-server guess.
Logic:
1. Measure total GGUF file size (including split shards)
2. Query free memory per GPU via nvidia-smi
3. If the model fits in 70% of the most-free GPU's memory,
pin to that single GPU (CUDA_VISIBLE_DEVICES=X, no --fit)
4. If it needs multiple GPUs, pick the N most-free GPUs
(CUDA_VISIBLE_DEVICES=X,Y, no --fit)
5. If it's too large for all GPUs combined, omit
CUDA_VISIBLE_DEVICES and use --fit on to let llama-server
handle partial offloading
The 70% threshold accounts for KV cache and compute buffers
that sit on top of the model weights.
Removed the -ngl parameter (was hardcoded to -1). llama-server's
default of "auto" handles layer offloading correctly, especially
with --fit on for oversized models.
Tested on 8x B200:
- 1B model (0.75 GB): picks 1 GPU, no --fit
- 27B model (17 GB): picks 1 GPU, no --fit
- 405B model (230 GB): picks 2 GPUs, no --fit
- 2TB model: all GPUs, --fit on
Refactor command building (deduplicate HF/local paths) and add
flags for better performance:
- --parallel 1: studio is single-user, so only 1 inference slot
is needed. The previous auto-detect picked 4 slots, wasting
VRAM on 3 unused KV caches.
- --flash-attn on: force flash attention for faster inference.
Default is "auto" which may not always enable it.
- --fit on: auto-adjust parameters to fit in available device
memory. Already the default but now explicit.
Also cleaned up the duplicated command building for HF vs local
mode into a single block.
Remove the hard max_tokens=2048 default and le=4096 cap for GGUF
chat completions. When max_tokens is not set (None), the field is
omitted from the llama-server payload entirely, letting the model
generate until it produces an EOS token or hits the context limit.
This is critical for thinking/reasoning models (Qwen3.5, DeepSeek-R1,
etc.) where the thinking phase alone can consume 1000+ tokens before
the actual answer. With the previous 2048 default, simple questions
like "What is 2+2?" used all tokens on thinking and produced empty
visible responses.
Changes:
- llama_cpp.py: max_tokens default None, only include in payload
when explicitly set
- models/inference.py: default None, remove le=4096 cap
- routes/inference.py: pass max_tokens directly, no "or 2048" fallback
llama-server handles omitted max_tokens gracefully (generates until
EOS or context limit). The context size (-c flag, default 4096) acts
as the hard upper bound.
llama-server sends thinking/reasoning tokens as "reasoning_content"
in the SSE delta (separate from "content"). The studio was only
reading delta.content, so all reasoning tokens from models like
Qwen3.5, Qwen3-Thinking, DeepSeek-R1, etc. were silently dropped.
This caused "replies with nothing" for thinking models: the model
would spend its entire token budget on reasoning, produce zero
content tokens, and the user would see an empty response.
Fix: read reasoning_content from the delta and wrap it in
<think>...</think> tags. The frontend already has full support
for these tags (parse-assistant-content.ts splits them into
reasoning parts, reasoning.tsx renders a collapsible "Thinking..."
indicator).
Verified with Qwen3.5-27B-GGUF (UD-Q4_K_XL):
- Before: "What is 2+2?" -> empty response (all tokens in reasoning)
- After: shows collapsible thinking + answer "4"
* fix: resolve compare mode deadlock, cancel_event poisoning, and add dispatcher-based IPC optimization
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* revert to 2048 tokens
* refactor: extract dispatcher timeout values into named constants
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* fix: guard dispatcher shutdown against active compare mailboxes
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
* miscallenous studio
* chore: upload dataset misc
* chore: redudancy studio cleanup
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* fix: adress the pr comments
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* fix: adress comments about recipes
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
* quiet llama.cpp build, smarter CUDA install via winget, accept Python 3.11-3.13
* studio: hide Python traceback when setup script exits with error
* setup.ps1: auto-add Python Scripts dir to PATH so 'unsloth' command works in new terminals
* setup.ps1: fix GPU check to run nvidia-smi instead of just checking command existence
* setup.ps1: fix PATH check to use exact entry comparison instead of substring match
* setup.ps1: validate Python probe exit code before persisting Scripts PATH
* fix: quotation marks
* diceware passphrase generation
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
---------
Co-authored-by: Roland Tannous <rolandtannous@gravityq.ai>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Replace _in_virtualenv() heuristic with a runtime probe. At
bootstrap time, try a dry-run uv install without --system. If
that fails (exit code 2, "No virtual environment found"), retry
with --system to confirm it works. This handles all environments
correctly: venvs, Colab (system Python), local machines, containers.
Three fixes based on review:
1. Make uv truly optional: _bootstrap_uv() now only checks if uv is
already on PATH. It no longer tries to pip install uv. If uv is
not present, pip is used with zero changes to behavior.
2. Add --system flag for Colab: on Colab there is no venv (packages
install into system Python). uv requires --system in this case,
otherwise it errors with "No virtual environment found". Added
_in_virtualenv() check that detects VIRTUAL_ENV, sys.real_prefix,
or sys.base_prefix != sys.prefix.
3. Fix label printed twice on uv fallback: when uv fails and falls
back to pip, the label now says "(pip)" to distinguish from the
initial uv attempt, instead of printing the same label twice.
Tested:
- venv path: no --system flag, uv installs correctly
- no-venv path (Colab sim): --system flag added automatically
- full unsloth studio setup + training run (Llama-3.2-1B, 10 steps)
install_python_stack.py:
- Print uv error output on failure for debuggability
- Refactor pip_install() to use early return after uv success,
removing duplicated pip command path
setup.sh:
- Guard nvidia-smi command substitution with || true so it does
not abort the script under set -euo pipefail when nvidia-smi
fails (e.g., containerized environments, driver quirks)
- Read all GPU compute capabilities and deduplicate, so
mixed-GPU hosts get kernels built for all present architectures
instead of only the first GPU
Restore separate cmake --build calls for llama-server and
llama-quantize on both setup.sh and setup.ps1. The combined
approach made llama-quantize failure fatal, but it was originally
best-effort (|| true on Linux, [WARN] on Windows). The timing
savings from combining was only ~2.7s, not worth the semantic
change.
The Ninja + arch detection speedups are preserved (55s vs 1m 37s).
Build llama-server and llama-quantize in a single cmake --build
invocation on Windows, matching the same optimization done in
setup.sh. This allows MSBuild to better parallelize the two targets.
The Visual Studio generator is kept as-is (not switching to Ninja on
Windows since VS generator is the standard approach and interacts
with MSBuild).
Three improvements to the llama.cpp build step in setup.sh:
1. Detect GPU compute capability via nvidia-smi and limit
CMAKE_CUDA_ARCHITECTURES to the current GPU. Without this, cmake
builds for all default CUDA architectures which is very slow.
2. Use Ninja build generator when available. Ninja has better
parallelism than Make for CUDA compilation.
3. Build both llama-server and llama-quantize targets in a single
cmake --build invocation for better parallelism.
4. Add --threads=0 to CMAKE_CUDA_FLAGS for multi-threaded nvcc
compilation.
Measured on 192-core machine with B200 (sm_100):
Make (all archs): very slow (minutes for each arch)
Make (single arch): 1m 37s
Ninja (single arch): 55s
Speedup: ~1.7x
Combined with the uv change, total setup goes from ~4m 35s to ~1m 40s.
Replace pip with uv in install_python_stack.py to speed up the Python
dependency installation phase of `unsloth studio setup`.
- Add _bootstrap_uv() that checks for uv on PATH, and if not found,
installs it via pip. Falls back to pip if uv is unavailable.
- Translate pip flags to uv equivalents (--no-cache-dir dropped since
uv caching is fast, --force-reinstall becomes --reinstall).
- Add --torch-backend=auto so uv auto-detects CUDA version for
PyTorch ecosystem packages.
- Per-install fallback: if any uv install step fails, it retries that
step with pip before exiting.
Measured on clean venv setup:
Python packages (pip): 2m 28s
Python packages (uv): 18s
Speedup: ~8x
Total setup time goes from ~4m 35s to ~2m 30s (llama.cpp build is
now the bottleneck at 1m 40s).
Related to #1615
Add documentation and function for exporting models from Colab to local machines.
* **README.md**: Add a new section titled "Exporting Models from Colab to Local Machine" under "✨ Finetune for Free" with detailed steps for exporting models from Colab to local machines.
* **CONTRIBUTING.md**: Add a note about the new documentation section for exporting models from Colab.
* **unsloth/save.py**: Add a new function `export_model_to_local` to handle exporting models from Colab to local machines.
(cherry picked from commit 0361bd658f)
Editable installs (-e) work via a .pth file that is only processed at
Python startup. In Colab the kernel is already running when setup.sh
installs the plugin, so the .pth file never gets picked up and
data_designer_unstructured_seed is not importable.
Remove -e so pip copies the package files directly into site-packages,
which the live kernel can find immediately. Local venv installs are
unaffected since the venv is always created fresh before install.
* fix(seed): disable remote code execution for seed inspect loads
* fix(test): use __file__-relative path in seed test
The test used a CWD-relative path (`studio/backend/routes/...`) which
only resolved when pytest was invoked from the repo root. Use
`Path(__file__).resolve()` so the test passes regardless of CWD.
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
---------
Co-authored-by: Test <test@test.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
* fix: disable remote code loading for ai-assist model hint lookup
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
---------
Co-authored-by: Roland Tannous <115670425+rolandtannous@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
The studio was disabling flex attention entirely on Blackwell+ GPUs
(sm_120 and above) by setting UNSLOTH_ENABLE_FLEX_ATTENTION=0 at
startup. This was a workaround for the flex_attention backward kernel
exceeding shared memory limits on these GPUs.
The root cause is now fixed in unsloth-zoo (PR #542) which patches the
backward kernel config selection to generate safe fallback configs that
fit within the GPU's shared memory limit. With that fix, flex attention
works correctly on Blackwell GPUs and provides a ~1.3x speedup over
the SDPA fallback.
