Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time
Apr 30, 2021
Mar 4, 2021
Apr 30, 2021
Apr 30, 2021


Build Status License Downloads

Go Module Go version Go Report Card

All Contributors

Contributor Covenant

Please Note: main is now v4.0.0 and the code for v3.x can be found in the main-v3 branch!

k3s in docker

k3s is the lightweight Kubernetes distribution by Rancher: rancher/k3s

k3d creates containerized k3s clusters. This means, that you can spin up a multi-node k3s cluster on a single machine using docker.





Note: In May 2020 we upgraded from v1.7.x to v3.0.0 after a complete rewrite of k3d! Note: In January 2021 we upgraded from v3.x.x to v4.0.0 which includes some breaking changes!

Platform Stage Version Release Date
GitHub Releases stable GitHub release (latest by date) GitHub Release Date
GitHub Releases latest GitHub release (latest by date including pre-releases) GitHub (Pre-)Release Date
Homebrew - homebrew -
Chocolatey stable chocolatey -


You have several options there:

  • use the install script to grab the latest release:

    • wget: wget -q -O - | bash
    • curl: curl -s | bash
  • use the install script to grab a specific release (via TAG environment variable):

    • wget: wget -q -O - | TAG=v4.0.0 bash
    • curl: curl -s | TAG=v4.0.0 bash
  • use Homebrew: brew install k3d (Homebrew is available for MacOS and Linux)

  • install via MacPorts: sudo port selfupdate && sudo port install k3d (MacPorts is available for MacOS)

  • install via AUR package rancher-k3d-bin: yay -S rancher-k3d-bin

  • grab a release from the release tab and install it yourself.

  • install via go: go install (Note: this will give you unreleased/bleeding-edge changes)

  • use Chocolatey: choco install k3d (Chocolatey package manager is available for Windows)



  1. Clone this repo, e.g. via git clone or go get
  2. Inside the repo run
    • 'make install-tools' to make sure required go packages are installed
  3. Inside the repo run one of the following commands
    • make build to build for your current system
    • go install to install it to your GOPATH (Note: this will give you unreleased/bleeding-edge changes)
    • make build-cross to build for all systems


Check out what you can do via k3d help or check the docs @

Example Workflow: Create a new cluster and use it with kubectl

  1. k3d cluster create CLUSTER_NAME to create a new single-node cluster (= 1 container running k3s + 1 loadbalancer container)
  2. [Optional, included in cluster create] k3d kubeconfig merge CLUSTER_NAME --kubeconfig-switch-context to update your default kubeconfig and switch the current-context to the new one
  3. execute some commands like kubectl get pods --all-namespaces
  4. k3d cluster delete CLUSTER_NAME to delete the default cluster


  1. Join the Rancher community on slack via
  2. Go to and join our channel #k3d
  3. Start chatting


This repository is based on @zeerorg's zeerorg/k3s-in-docker, reimplemented in Go by @iwilltry42 in iwilltry42/k3d, which got adopted by Rancher inrancher/k3d.

Related Projects

  • k3x: GUI (Linux) to k3d
  • vscode-k3d: vscode plugin for k3d
  • AbsaOSS/k3d-action: fully customizable GitHub Action to run lightweight Kubernetes clusters.
  • AutoK3s: a lightweight tool to help run K3s everywhere including k3d provider.


k3d is a community-driven project and so we welcome contributions of any form, be it code, logic, documentation, examples, requests, bug reports, ideas or anything else that pushes this project forward.

Please read our Contributing Guidelines and the related Code of Conduct.

Contributor Covenant


Thanks goes to these wonderful people (emoji key):

Thorsten Klein

💻 📖 🤔 🚧

Rishabh Gupta

🤔 💻

Louis Tournayre


Lionel Nicolas


Toon Sevrin


Dennis Hoppe

📖 💡

Jonas Dellinger





💻 🤔 🔌

Nuno do Carmo

🖋 💬

Erwin Kersten


Alex Sears


This project follows the all-contributors specification. Contributions of any kind welcome!