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. For Blackwell and 50-series GPUs, use this same image - no separate one needed.

Copy

docker run -d -e JUPYTER_PASSWORD="mypassword" \
  -p 8888:8888 -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:

# Generate new key pair
ssh-keygen -t rsa -b 4096 -f ~/.ssh/container_key

# Use the public key in docker run
-e "SSH_KEY=$(cat ~/.ssh/container_key.pub)"

# Connect via SSH
ssh -i ~/.ssh/container_key -p 2222 unsloth@localhost

🦥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.)

⚙️ Advanced Settings

# Generate SSH key pair
ssh-keygen -t rsa -b 4096 -f ~/.ssh/container_key

# Connect to container
ssh -i ~/.ssh/container_key -p 2222 unsloth@localhost

-p <host_port>:<container_port>

• Jupyter Lab: -p 8000:8888

• SSH access: -p 2222:22

-v <local_folder>:<container_folder>

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

🔒 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