Install Unsloth via Docker

Learn how to use our Docker containers with all dependencies pre-installed for immediate installation. No setup required, just run and start training!

Unsloth Docker image: unsloth/unsloth

⚡ Quickstart

1

Install Docker and NVIDIA Container Toolkit.

Install Docker via Linux or Desktop (other). Then install NVIDIA Container Toolkit:

Copy

export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.17.8-1
sudo apt-get update && sudo apt-get install -y \
  nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}

2

Run the container.

unsloth/unsloth is Unsloth's only Docker image.

Copy

docker run -d -e JUPYTER_PASSWORD="mypassword" \
  -p 8888:8888 -p 8000:8000 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth

3

Access Jupyter Lab

Go to http://localhost:8888 and open Unsloth.

Access the unsloth-notebooks tabs to see Unsloth notebooks.

4

Start training with Unsloth

If you're new, follow our step-by-step Fine-tuning Guide, RL Guide or just save/copy any of our premade notebooks.

📂 Container Structure

• /workspace/work/ — Your mounted work directory

• /workspace/unsloth-notebooks/ — Example fine-tuning notebooks

• /home/unsloth/ — User home directory

📖 Usage Example

Full Example

docker run -d -e JUPYTER_PORT=8000 \
  -e JUPYTER_PASSWORD="mypassword" \
  -e "SSH_KEY=$(cat ~/.ssh/container_key.pub)" \
  -e USER_PASSWORD="unsloth2024" \
  -p 8000:8000 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth

Setting up SSH Key

If you don't have an SSH key pair:

🦥Why Unsloth Containers?

• Reliable: Curated environment with stable & maintained package versions. Just 7 GB compressed (vs. 10–11 GB elsewhere)

• Ready-to-use: Pre-installed notebooks in /workspace/unsloth-notebooks/

• Secure: Runs safely as a non-root user

• Universal: Compatible with all transformer-based models (TTS, BERT, etc.)

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]

• On Linux, make sure the NVIDIA Container Toolkit is installed.

• On Windows:

  • Check that nvcc --version matches the CUDA version shown in nvidia-smi

  • Follow: https://docs.docker.com/desktop/features/gpu/

⚙️ Advanced Settings

• Jupyter Lab: -p 8000:8888

• SSH access: -p 2222:22

🔒 Security Notes

• Container runs as non-root unsloth user by default

• Use USER_PASSWORD for sudo operations inside container

• SSH access requires public key authentication