🦥 Unsloth Studio

A modern, full-stack web interface for fine-tuning, managing, and chatting with large language models — locally or in the cloud.

Features • Quick Start • API Reference • Project Structure

---

Features

Area	Capabilities
Training	Configure and launch LoRA / QLoRA fine-tuning jobs with real-time SSE progress streaming, live loss charts, and one-click stop / resume
Model Management	Browse, load, and manage Hugging Face hub models and local checkpoints
Inference	Interactive chat playground for testing fine-tuned models
Dataset Tools	Upload, preview, and prepare datasets (JSON, CSV, Parquet, PDF, DOCX)
Export	Export & push trained adapters to the Hugging Face Hub
Auth	Token-based authentication with JWT access / refresh flow and first-time setup token

Quick Start

Prerequisites

Requirement	Linux / WSL	Windows
GPU	NVIDIA GPU with working driver	NVIDIA GPU with working driver
Python	3.11 – 3.13	3.11 – 3.13
Git	Pre-installed on most distros	Auto-installed by setup script (via winget)
CMake	Pre-installed or sudo apt install cmake	Auto-installed by setup script (via winget)
C++ compiler	build-essential (auto-detected)	Visual Studio Build Tools 2022 (auto-installed by setup script)
CUDA Toolkit	Optional — setup auto-detects nvcc	Auto-installed by setup script (version matched to driver)

Note

On WSL, the setup script will also run sudo apt-get install build-essential cmake curl git libcurl4-openssl-dev so that GGUF export works in non-interactive subprocesses. You may be prompted for your password during setup.

---

Linux / Windows WSL

# 1. Clone the repo
git clone https://github.com/unslothai/unsloth-studio.git
cd unsloth-studio

# 2. Run setup (installs Node, builds frontend, creates .venv, builds llama.cpp)
bash setup.sh

# 3. Open a new terminal (or source your shell rc), then launch:
unsloth-studio -H 0.0.0.0 -p 8000

What does setup.sh do?

1. Installs Node.js ≥ 20 via nvm (if needed)
2. Runs npm install && npm run build for the React frontend
3. Detects the best Python 3.11 – 3.13 on your system and creates a .venv
4. Installs all Python dependencies (unsloth, PyTorch with CUDA, triton kernels, etc.)
5. On WSL: pre-installs build dependencies via apt-get
6. Clones and builds llama.cpp at ~/.unsloth/llama.cpp (GPU-accelerated if CUDA is found)
7. Registers unsloth-studio and unsloth-ui shell aliases in your shell rc (bash, zsh, fish, or ksh)

---

Windows (Native)

Important

Requires an NVIDIA GPU — CPU-only machines are not supported on Windows.

# 1. Clone the repo
git clone https://github.com/unslothai/unsloth-studio.git
cd unsloth-studio

# 2. Run setup (Right-click → "Run with PowerShell", or from a terminal):
.\setup.bat
# Or directly:
powershell -ExecutionPolicy Bypass -File setup.ps1

After setup completes, open a new terminal and run:

# PowerShell
unsloth-studio -H 0.0.0.0 -p 8000

# Or cmd.exe
unsloth-studio -H 0.0.0.0 -p 8000

What does setup.ps1 do?

1. Enables Windows Long Paths (required for deep dependency trees — prompts for UAC)
2. Auto-installs missing system tools via winget: Git, CMake, Visual Studio Build Tools 2022, CUDA Toolkit (version-matched to your driver), Node.js LTS, Python 3.12, OpenSSL dev
3. Builds the React frontend (npm install && npm run build)
4. Creates a .venv and installs all Python dependencies (including CUDA-enabled PyTorch from the official index)
5. Sets TORCHINDUCTOR_CACHE_DIR=C:\tc to avoid Windows MAX_PATH issues with Triton
6. Clones and builds llama.cpp at %USERPROFILE%\.unsloth\llama.cpp with CUDA + Visual Studio
7. Registers unsloth-studio and unsloth-ui commands in both PowerShell profile and cmd.exe (via batch files on PATH)

---

Google Colab

The setup script auto-detects Colab and installs everything into the existing system Python (no venv):

!bash setup.sh

---

Launching the Studio

After setup on any platform, the command is the same:

unsloth-studio -H 0.0.0.0 -p 8000

Flag	Description
-H / --host	Bind address (0.0.0.0 for all interfaces, 127.0.0.1 for local only)
-p / --port	Port number (default: 8000)

On first launch, a one-time setup token is printed to the console. Open the URL shown in your browser and use this token to create your admin account.

Tip

This repo is in active development. After pulling new changes, always re-run the setup script (bash setup.sh or .\setup.bat) to pick up dependency and build updates.

API Reference

All endpoints require a valid JWT Authorization: Bearer <token> header (except /api/auth/* and /api/health).

Method	Endpoint	Description
GET	/api/health	Health check
GET	/api/system	System info (GPU, CPU, memory)
POST	/api/auth/signup	Create account (requires setup token on first run)
POST	/api/auth/login	Login and receive JWT tokens
POST	/api/auth/refresh	Refresh an expired access token
GET	/api/auth/status	Check if auth is initialized
POST	/api/train/start	Start a training job
POST	/api/train/stop	Stop a running training job
POST	/api/train/reset	Reset training state
GET	/api/train/status	Get current training status
GET	/api/train/metrics	Get training metrics (loss, LR, steps)
GET	/api/train/stream	SSE stream of real-time training progress
GET	/api/models/	List available models
POST	/api/inference/chat	Send a chat message for inference
GET	/api/datasets/	List / manage datasets

Full interactive docs are available at /docs (Swagger UI) and /redoc when the server is running.

CLI Commands

The Unsloth CLI (cli.py) provides the following commands:

Usage: cli.py [COMMAND]

Commands:
  train             Fine-tune a model
  inference         Run inference on a trained model
  export            Export a trained adapter
  list-checkpoints  List saved checkpoints
  ui                Launch the Unsloth Studio web UI
  studio            Launch the studio (alias)

Project Structure

new-ui-prototype/
├── cli.py                     # CLI entry point
├── cli/                       # Typer CLI commands
│   └── commands/
│       ├── train.py
│       ├── inference.py
│       ├── export.py
│       ├── ui.py
│       └── studio.py
├── setup.sh                   # Bootstrap script (Linux / WSL / Colab)
├── setup.ps1                  # Bootstrap script (Windows native)
├── setup.bat                  # Wrapper to launch setup.ps1 via double-click
├── install_python_stack.py    # Cross-platform Python dependency installer
└── studio/
    ├── backend/
    │   ├── main.py            # FastAPI app & middleware
    │   ├── run.py             # Server launcher (uvicorn)
    │   ├── auth/              # Auth storage & JWT logic
    │   ├── routes/            # API route handlers
    │   │   ├── training.py
    │   │   ├── models.py
    │   │   ├── inference.py
    │   │   ├── datasets.py
    │   │   └── auth.py
    │   ├── models/            # Pydantic request/response schemas
    │   ├── core/              # Training engine & config
    │   ├── utils/             # Hardware detection, helpers
    │   └── requirements.txt
    ├── frontend/
    │   ├── src/
    │   │   ├── features/      # Feature modules
    │   │   │   ├── auth/      # Login / signup flow
    │   │   │   ├── training/  # Training config & monitoring
    │   │   │   ├── studio/    # Main studio workspace
    │   │   │   ├── chat/      # Inference chat UI
    │   │   │   ├── export/    # Model export flow
    │   │   │   └── onboarding/# Onboarding wizard
    │   │   ├── components/    # Shared UI components (shadcn)
    │   │   ├── hooks/         # Custom React hooks
    │   │   ├── stores/        # Zustand state stores
    │   │   └── types/         # TypeScript type definitions
    │   ├── package.json
    │   └── vite.config.ts
    └── tests/                 # Backend test suite

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

Copyright © 2026 Unsloth AI.