Install Unsloth via Docker

Learn how to run and train models with the Unsloth Docker container. No setup required - all dependencies are pre-installed. Just pull the image and start running and training models on your local NVIDIA or AMD GPUs.

Quickstart

This guide section applies to systems with NVIDIA GPUs. If you have AMD see here.

Linux / WSL

Windows (PowerShell)

To get Unsloth's Docker on NVIDIA GPUs, run the following in terminal:

Copy

docker run -d --name unsloth --gpus all --ipc=host \
  --ulimit memlock=-1 --ulimit stack=67108864 \
  -p 8000:8000 -p 8888:8888 \
  -e JUPYTER_PASSWORD="mypassword" \
  -v "$PWD":/workspace/host \
  -v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
  -v unsloth-studio:/opt/unsloth-studio \
  unsloth/unsloth

• Run it from your project folder, because that folder ($PWD) becomes /workspace/host.

• What the flags do: exposing ports 8000 (Unsloth Studio) and 8888 (JupyterLab); the three -v flags keep your files, models and Unsloth Studio data.

• Requirement: NVIDIA driver 570.26 or newer.

Run the following in Powershell:

• Run it from your project folder, because that folder (${PWD}) becomes /workspace/host.

• What the flags do: exposing ports 8000 (Unsloth Studio) and 8888 (JupyterLab); the three -v flags keep your files, models and Unsloth Studio data.

• Requirement: NVIDIA driver 570.26 or newer.

Prerequisites

If you do not have Docker installed for NVIDIA Container Toolkit, follow the below:

Linux / WSL

Windows

Install Docker Engine or Docker Desktop, if you haven't already:

If you have an NVIDIA GPU, install NVIDIA Container Toolkit if you haven't already:

Install Docker Desktop and the NVIDIA driver.

Install Docker Desktop for Windows and the latest NVIDIA Windows driver. Then update WSL in PowerShell:

In Docker Desktop settings, select General and check that Use the WSL 2 based engine is enabled. Wait for the engine to start before continuing.

No separate NVIDIA Container Toolkit installation is needed. Windows GPU troubleshooting.

AMD Quickstart

This guide section applies to systems with AMD GPUs. If you have NVIDIA see here.

If you do not have Docker installed, run the following command:

AMD needs no container toolkit, only the amdgpu driver on the host. On Windows, install Docker Desktop and the AMD driver with WSL2 support.

📖 Usage Guides

Unsloth Studio Setup

Unsloth Studio comes pre-installed, so you can chat with models, fine-tune them and generate images from the same Docker container.

Chat with a model

1

Choose and download a model

Open Select model at the top of the page. Browse Recommended, or enter a model name and click Search Hub to search Hugging Face. You can also browse models in Model hub.

For GGUF models, choose a quantization that fits your available RAM and VRAM. Avoid variants marked OOM.

Wait for the model to finish downloading and loading before sending your first message. You can select downloaded models again from On Device.

Downloaded models are stored in /workspace/.cache/huggingface. With the Quickstart volume mount, this cache is shared with notebooks and stays on your computer even if you remove the container.

2

Send a message

Once the model is ready, type a message and press Enter. Try:

Explain how Docker containers differ from virtual machines.

See the Unsloth Studio Chat guide for web search and more chat settings.

Train a model

You can train models across text, vision and audio, with support for embeddings and image diffusion too. All from the same Docker image.

Choose a model and dataset

Select Train and open Configure. Choose a model and training method, then select a Hugging Face dataset or upload your own.

Start training

Review Parameters in Simple or Advanced mode, then click Start Training. Track progress, loss and GPU usage in Current Run.

Try your trained model

When training finishes, click Compare in Chat. Test the original and fine-tuned models with the same prompts to see how their responses differ.

See the Studio training guide for more detail, or use Data Recipes to prepare your dataset.

Generate images

1

Open Images and choose a model

Select Images in the sidebar. The Create workflow opens by default.

Open Select image model and choose from Recommended, such as Z-Image-Turbo. For GGUF models, pick a quantization that fits your device. TIGHT may run slowly; OOM is unlikely to fit.

2

Enter a prompt and generate

Describe the image you want to create. For example:

Top-down shot of a koi pond in a Japanese garden, dozens of orange, white and black koi swimming in tight formation, water clear enough to see the stone bottom, red maple leaves floating on the surface. Bright midday light, saturated colour, crisp reflections. Realistic photo, 50mm.

Leave the image settings at their defaults and click Generate.

Open your image in the gallery and click Download to save it, or Recipe to reuse its prompt and settings.

Transform, Inpaint and Edit depend on the loaded model. See the image diffusion guide for supported workflows and settings.

Access JupyterLab

The Unsloth Docker image includes JupyterLab and ready-to-use notebooks.

Open http://localhost:8888 and sign in. Use the JUPYTER_PASSWORD you chose when starting the container. If you did not set one, use the generated password printed in the container log.

JupyterLab passwords are set when the container is created. To change it, remove and recreate the container with a new password.

After signing in, you’ll see Unsloth Notebooks, with folders grouped by model and task.

These folders contain shortcuts to the notebook files in /workspace/unsloth-notebooks. Each time the container starts, the notebooks are refreshed from GitHub without overwriting your edits.

Double-click 01 Main Notebooks to browse examples, or choose a category such as vision, speech or reinforcement learning.

Fine-tune a model in a notebook

Unload any model loaded in Unsloth Studio before you start training, so the notebook has the GPU memory it needs.

Open a notebook in 01 Main Notebooks and follow its instructions. Press Shift+Enter to run each cell in order. The first run downloads the model into the Hugging Face cache.

For example, Gemma3_(4B)-Vision.ipynb guides you through fine-tuning Gemma 3 4B to turn images of equations into LaTeX.

After training, test your model using the notebook's Inference section. It tests the trained model on an equation image. The equation is below, recreated at higher resolution here for readability.

The model generates LaTeX from the original dataset image. It prints the LaTeX result below the cell.

Save and export your model

Follow the notebook's Saving section to save your trained LoRA adapters or export your merged model.

A relative path like "gemma_3_lora" saves next to the notebook, inside /workspace/Unsloth Notebooks/.... That folder is inside the container, so it is deleted when you remove the container. To keep your results on your computer, save under /workspace/host.

• Save LoRA adapters locally: This cell runs by default. Change the path to /workspace/host.

• Export merged 16-bit model: In the export cell, change if False: to if True: for the option you want. Only pick one.

• Upload to Hugging Face: You need a token with write access to upload. Replace the YOUR_USERNAME and YOUR_HF_TOKEN placeholders with your own details.

For more guidance, see our Fine-tuning Guide, RL Guide, and notebook collection.

Stop, restart and update the container

Commands take the container name or id, not the image name unsloth/unsloth.

Shut down the container but keep it:

Bring it back in the same state:

Find your container again, running or not:

Stop and delete the container:

Deleting the container does not delete your models, your host files (/workspace/host), or Unsloth Studio data (accounts, chats, and exports). A new container with the same -v flags continues where you left off, and your Unsloth password stays the same. Anything else written inside the container is lost.

To delete Unsloth Studio's data permanently, remove its volume:

To update to the latest Unsloth version, pull the new image:

Then remove the old container and run the Quickstart command again with the same flags. Your models, files and Unsloth Studio data carry over.

Connect over SSH

SSH is off unless you set SSH_KEY or PUBLIC_KEY. You connect as the root user with key-only authentication on port 22 inside the container.

Generate an SSH key:

The SSH key is applied when the container is created, so you must recreate the container to add it. Use this full command to map the SSH port to 2222 on your host, set your passwords, and mount your volumes.

UNSLOTH_STUDIO_PASSWORD applies only the first time the unsloth-studio volume is used. See Advanced Settings below for all environment variables, volumes and ports.

Connect to the container:

📂 Container Structure

• /workspace/host/ — Your mounted work directory

• /workspace/.cache/huggingface — Model and dataset downloads

• /workspace/.cache/triton — Compiled Triton kernels

• /workspace/unsloth-notebooks/ — Example fine-tuning notebooks, including your edits

• /workspace/Unsloth Notebooks — Example fine-tuning notebooks grouped by topic, rebuilt on each start

• /opt/unsloth-studio — Unsloth Studio's accounts, chats, outputs, exports and runs

Troubleshooting

Unsloth not detecting or using my GPU

If the model is not using your GPU specifically for Docker, try:

Pulling the latest image manually:

• Start the container with GPU access:

  • docker run: --gpus all

  • Docker Compose: capabilities: [gpu]

  • AMD: --device /dev/kfd --device /dev/dri plus the --group-add ids (the $GPU_FLAGS block in Quickstart)

• On Linux (NVIDIA), make sure the NVIDIA Container Toolkit is installed, and docker is restarted after installing it.

• On Windows (NVIDIA):

  • Run docker exec unsloth nvidia-smi. If it lists your GPU, the container can see it.

  • Follow Docker's guide

• On AMD: run docker exec unsloth rocm-smi. If it lists your GPU, the container can see it. A permission error on /dev/kfd means the --group-add ids were missing.

Port is already allocated

Change the host side port, e.g. -p 8001:8000, then open http://localhost:8001.

Unsloth Studio stopped responding after an hour

Unsloth Studio auto shuts down if the auto generated password is not changed. Run docker restart unsloth to start it again and change password.

Files in your project folder are owned by root

The container runs as root, so use sudo chown, or core with --user.

⚙️ Advanced Settings

Environment variables

Pass any of these to docker run with -e NAME=value or --env-file. These apply to both unsloth/unsloth and unsloth/unsloth-rocm.

Volume

Anything not on a volume is lost when the container is removed. Mount these with -v <host path or volume name>:<container path>.

• /workspace is the working directory and the folder JupyterLab opens in.

• Use a named volume for /opt/unsloth-studio, not a host folder. Unsloth Studio needs symlinks there, and a Windows or macOS host folder may not allow them, which stops the container at start.

• To give Unsloth Studio or JupyterLab more of your files, mount more folders under /workspace, e.g. -v /data/datasets:/workspace/datasets, and refer to them by that container path.

Ports

Map a container port to any free host port with -p <host>:<container>. For example, to enable SSH on host port 2222:

🔒 Security Notes

• The container runs as root. Use unsloth/unsloth:core with --user <uid>:<gid> if you need mounted files owned by your host user.

• SSH is off unless SSH_KEY or PUBLIC_KEY is set. It is key-only, as root, on port 22.

• Published ports listen on every interface. On a cloud host, bind to 127.0.0.1 or use -e UNSLOTH_STUDIO_SECURE=1.

• JupyterLab is a full shell. Anyone who can log in to JupyterLab can run any command in the container. Unsloth Studio and JupyterLab serve plain HTTP, so do not expose them to the internet directly.

• Unsloth Studio tools can run code. Studio's server-side tools are on by default and can run commands inside the container. Only mount host folders you are comfortable giving the container access to.

• Environment variables are visible to Docker users. Values passed with -e or --env-file, including tokens and passwords, show up in docker inspect. Anyone with access to the Docker daemon can read them.