# Unsloth Core vs Unsloth Studio: Architecture, Usage Patterns, and Key Differences

> Compare Unsloth Core and Unsloth Studio. Discover their architecture, usage patterns, and key differences to choose the right tool for your AI development needs.

- Repository: [Unsloth AI/unsloth](https://github.com/unslothai/unsloth)
- Tags: architecture
- Published: 2026-03-20

---

**Unsloth Core is a pure Python library exposing programmable training and inference APIs, while Unsloth Studio wraps that engine inside a browser-based UI with an isolated virtual environment and visual workflow editor.**

When navigating the unslothai/unsloth repository, you encounter two distinct interfaces for fine-tuning large language models. The difference between Unsloth Core vs Unsloth Studio centers on control versus convenience: Core targets developers who need scripted automation, while Studio provides a password-protected web interface for interactive, low-code experimentation.

## Architectural Purpose and Target Audience

**Unsloth Core** functions as the foundational engine. Implemented primarily in [`unsloth/trainer.py`](https://github.com/unslothai/unsloth/blob/main/unsloth/trainer.py), it exposes the `UnslothTrainer` class—a comprehensive interface for model loading, LoRA preparation, dataset formatting, and TRL-compatible training loops. Researchers and DevOps engineers use Core when embedding LLM workflows into existing Python codebases or CI/CD pipelines.

**Unsloth Studio**, defined in [`unsloth_cli/commands/studio.py`](https://github.com/unslothai/unsloth/blob/main/unsloth_cli/commands/studio.py), operates as a thin wrapper around Core. It launches a Flask-based HTTP server ([`studio/backend/run.py`](https://github.com/unslothai/unsloth/blob/main/studio/backend/run.py)) that serves a React frontend and translates user clicks into `UnslothTrainer` method calls. This targets educators, quick prototypers, and users who prefer drag-and-drop dataset recipes over writing boilerplate Python.

## Entry Points and Usage Patterns

The two components offer fundamentally different interaction models.

**Core Library Entry Points:**
- **Python API:** Import directly from the package root (e.g., `from unsloth.trainer import UnslothTrainer`).
- **CLI Commands:** Use `unsloth train`, `unsloth inference`, or `unsloth export` as implemented in [`unsloth_cli/commands/train.py`](https://github.com/unslothai/unsloth/blob/main/unsloth_cli/commands/train.py) and [`unsloth_cli/commands/inference.py`](https://github.com/unslothai/unsloth/blob/main/unsloth_cli/commands/inference.py).

**Studio Entry Point:**
- **Single Command:** Execute `unsloth studio` to bootstrap and launch the server. First-time runs trigger [`studio/setup.sh`](https://github.com/unslothai/unsloth/blob/main/studio/setup.sh) (or `setup.ps1` on Windows) to create an isolated Python environment under `~/.unsloth/studio/.venv`.

```python

# Unsloth Core: Direct Python scripting

from unsloth.trainer import UnslothTrainer

trainer = UnslothTrainer()
trainer.load_model(
    model_name="unsloth/gemma-2b",
    max_seq_length=4096,
    load_in_4bit=True,
)
trainer.prepare_model_for_training(
    training_type="lora",
    use_peft=True,
    gradient_checkpointing=True,
)
trainer.start_training(num_train_epochs=3, learning_rate=2e-4)

```

```bash

# Unsloth Studio: One-click UI launch

unsloth studio setup        # Creates isolated .venv (run once)

unsloth studio -p 8888      # Starts server; opens browser to http://localhost:8888

```

## Dependency Management and Environment Isolation

**Core** relies on standard Python packaging. Installing via `pip install unsloth` pulls in Hugging Face Transformers, TRL, and PyTorch dependencies directly into your active environment. No virtual-environment management occurs within the library itself, giving you full control over dependency resolution.

**Studio** enforces strict isolation. The setup scripts generate a dedicated `.venv` inside `~/.unsloth/studio`, install the UI's additional Node.js build assets, and run the server inside that sandbox. This prevents frontend dependencies from polluting your global Python environment but consumes additional disk space for the duplicate environment.

## Extensibility and Security Models

**Extensibility** diverges significantly between the two interfaces.

- **Core:** Grants direct access to optimizer states, custom callbacks, and dataset preprocessors. You can subclass `UnslothTrainer` in [`unsloth/trainer.py`](https://github.com/unslothai/unsloth/blob/main/unsloth/trainer.py) or monkey-patch TRL components before invoking `trainer.start_training()`.
- **Studio:** Limits modifications to exposed UI controls (hyperparameter sliders, data-recipe nodes). Advanced tweaks—such as implementing custom loss functions—require dropping to the Core API via the "Open Code" export feature.

**Security** reflects their deployment contexts.

- **Core:** Runs inside your existing Python process with no built-in authentication boundary. Security relies on your host environment's access controls.
- **Studio:** Implements password-protected access via `~/.unsloth/studio/auth/auth.db`. The `unsloth studio reset-password` command regenerates credentials, and the server binds to configurable hosts (`-H 0.0.0.0` for LAN access) with session management handled in [`studio/backend/run.py`](https://github.com/unslothai/unsloth/blob/main/studio/backend/run.py).

## How Studio Wraps Core

Despite the UI layer, Studio remains dependent on Core's implementation.

When a user clicks **Start Training** in the browser, the Studio server (running in [`studio/backend/run.py`](https://github.com/unslothai/unsloth/blob/main/studio/backend/run.py)) imports the trainer class and instantiates it in a background thread:

```python

# Conceptual flow inside Studio backend

from studio.backend.core.training.trainer import UnslothTrainer  # Wraps Core

trainer = UnslothTrainer()
trainer.load_model(...)  # Parameters from UI form fields

trainer.start_training(...)  # Runs in trainer.training_thread

```

Crucially, Core does **not** depend on Studio. The [`unsloth/trainer.py`](https://github.com/unslothai/unsloth/blob/main/unsloth/trainer.py) implementation contains no references to Flask, HTTP servers, or UI assets. This one-way dependency allows Core to be packaged independently in pip distributions and Docker images, while Studio remains an optional add-on.

## Shared Configuration Layer

Both interfaces consume the same configuration schema defined in [`unsloth_cli/config.py`](https://github.com/unslothai/unsloth/blob/main/unsloth_cli/config.py). The [`unsloth_cli/options.py`](https://github.com/unslothai/unsloth/blob/main/unsloth_cli/options.py) module maps these config fields to Typer CLI flags, ensuring that arguments like `--learning-rate` or `--max-seq-length` behave identically whether passed to `unsloth train` (Core) or preset in the Studio admin panel.

## Summary

- **Unsloth Core** ([`unsloth/trainer.py`](https://github.com/unslothai/unsloth/blob/main/unsloth/trainer.py)) provides the engine: importable Python classes for training, inference, and export with full programmatic control.
- **Unsloth Studio** ([`unsloth_cli/commands/studio.py`](https://github.com/unslothai/unsloth/blob/main/unsloth_cli/commands/studio.py)) provides the interface: a self-contained web UI with isolated virtual environments, visual dataset editors, and password authentication.
- **Dependency Isolation:** Core uses your existing Python environment; Studio creates `~/.unsloth/studio/.venv` via [`studio/setup.sh`](https://github.com/unslothai/unsloth/blob/main/studio/setup.sh).
- **Extensibility:** Core allows arbitrary code modification; Studio restricts workflow changes to UI-exposed parameters.
- **Entry Commands:** Core uses `unsloth train` or Python imports; Studio uses `unsloth studio` to launch the browser.

## Frequently Asked Questions

### Can I use Unsloth Studio without installing Unsloth Core?

No. Unsloth Studio imports and wraps the Core library internally. When you run `unsloth studio setup`, it installs the Core package inside the isolated Studio virtual environment. However, you cannot use Studio without Core being present, whereas Core functions perfectly well without Studio.

### Does Unsloth Studio support custom training callbacks and loss functions?

Only indirectly. The Studio UI exposes standard hyperparameters (learning rate, epochs, LoRA rank) through its Settings panel. To inject custom callbacks or modify the loss computation, you must export the generated Python script from Studio and run it directly against the Core API, or switch entirely to a Core-based Python workflow.

### Where does Unsloth Studio store authentication credentials?

Studio stores a hashed admin password in `~/.unsloth/studio/auth/auth.db`. During initial setup, the bootstrap script generates a temporary password saved to `~/.unsloth/studio/auth/.bootstrap_password`. You can rotate credentials anytime using the `unsloth studio reset-password` CLI command.

### Is the `UnslothTrainer` class identical in both Core and Studio?

Yes. Studio imports the trainer from [`studio/backend/core/training/trainer.py`](https://github.com/unslothai/unsloth/blob/main/studio/backend/core/training/trainer.py), which itself wraps the canonical implementation in [`unsloth/trainer.py`](https://github.com/unslothai/unsloth/blob/main/unsloth/trainer.py). This ensures that training behavior, optimizer defaults, and TRL compatibility remain consistent whether you script workflows in Core or click through the Studio wizard.