Linux
Requirements
Linux offers the best experience and fastest speed when working with containers. Besides avoiding the need for virtualization, when we develop we usually target Linux for production. File-system speed and permissions don't fit well when not using something made for Linux. Although there is love for all operating systems, Linux is really shining here.
Examples follow the Ubuntu distribution but can easily be adapted to any distribution.
01 Quick guide
Update your system
sudo apt-get update -y && sudo apt-get upgrade -y
Install development tools
sudo apt-get install -y build-essential
sudo apt install apt-transport-https ca-certificates curl software-properties-common -y
Install the docker container engine — this does NOT install Docker Desktop
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update -y
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker ${USER} # restart your terminal after adding your user to the docker group
sudo systemctl enable docker # start docker on boot
sudo systemctl restart docker # start docker now
sudo systemctl is-active docker # check docker is running
docker run hello-world # test — docker cli must run without sudo at this point
Install the podman container engine and podman-compose
sudo apt-get install -y podman podman-compose
Distributions usually ship very old podman versions. For more recent versions use the Alvistack project, which provides repositories for most Linux flavors.
Open Container Desktop
Connect to the System Podman or System Docker default connection and all should work.
02 Podman acting as Docker
This is referred to as Compatibility Mode — it should support all docker features, except the docker cli (use podman instead; you can alias it if you want).
Start the podman api listening to /var/run/docker.sock
export DOCKER_HOST=/var/run/docker.sock
podman system service --time=0 unix://${DOCKER_HOST} --log-level=debug
After this point, one can use podman or docker or any other tool that uses the socket.
03 Docker Desktop alternative
This is so easy — follow the Quick guide to support both docker and/or podman, or just skip the podman part and focus on docker only.
macOS
Requirements
On macOS, virtualization is required to support both docker and podman container engines. Homebrew is seriously recommended to simplify provisioning and setup. Due to high cost, Container Desktop does not currently afford an Apple subscription to digitally sign applications, nor a digital certificate.
Install homebrew (as a non-administrator user)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew update
brew upgrade
01 Quick guide
Install colima
brew install colima
Start the colima VM
colima start --vm-type=vz --vz-rosetta
This uses the native macOS virtualization framework, allowing even x86 container images to run and avoiding volume-mount file-system permission issues.
You can also use custom distribution images for the docker host OS — see the colima-core releases. After downloading the image of choice:
colima start --vm-type=vz --vz-rosetta --disk-image ~/Downloads/ubuntu-26.04-minimal-cloudimg-arm64-docker.qcow2
Install docker CLI tools and plugins
brew install docker docker-compose docker-buildx
This does not install Docker Desktop — only the command line tools that will use the colima docker engine. For the docker cli to find the plugins, add the following to your ~/.docker/config.json:
"cliPluginsExtraDirs": [
"$HOMEBREW_PREFIX/lib/docker/cli-plugins"
]
After all of the above you should have a completely compatible docker engine running on your Mac.
Allow the unsigned app to run (optional)
If you downloaded and installed Container Desktop for macOS, allow it to run despite the missing digital signature:
xattr -d com.apple.quarantine /Applications/Container\ Desktop.app
Open Container Desktop
Connect to the System Docker default connection and all should work.
02 Podman and Docker — best experience
Install lima
LIMA uses macOS native virtualization to provide Linux environments — it is like WSL, but for macOS.
brew install lima
Podman VM
limactl start podman # start the podman VM
limactl shell podman # login to the podman VM
Docker VM
limactl start docker # start the docker VM
limactl shell docker # login to the docker VM
03 Podman acting as Docker
This is referred to as Compatibility Mode — it should support all docker features, except the docker cli (use podman instead; alias it if you want).
Latest and greatest
Go to the Podman releases page and install the latest macOS pkg for your CPU. Consider:
- Upon installation, podman creates its own VM, also known as Podman Machine.
- It also sets the
DOCKER_HOSTenvironment variable to point at the podman unix socket, making it easy for the docker cli to use it.
Easiest (skip if using latest and greatest)
brew install podman
04 Docker Desktop alternative
Using colima offers the easiest experience — just follow the Quick guide to support docker in full compatibility.
(*) Optional: native docker CLI without homebrew
Not recommended due to complexity. Latest docker CLI and plugin binaries can be found at:
- Apple CPUs — download.docker.com/mac/static/stable/aarch64
- Intel CPUs — download.docker.com/mac/static/stable/x86_64
Windows
Requirements
On Windows, virtualization is required to support both podman and docker container engines. With WSL, the development experience has evolved — it is highly recommended to move away from msys/cygwin and just use WSL. Most of the time we deploy on Linux anyway, so an experience closer to reality is appropriate. It is also a good opportunity to learn Linux.
As a non-administrator user
winget install -e --id=Microsoft.WindowsTerminal
winget install "Container Desktop"
Enable and install WSL (as administrator)
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
winget install -e --id=Microsoft.WSL
Restart the computer, then set up the WSL distribution user account by starting wsl.exe in a Windows Terminal.
01 Quick guide
Enable and install WSL (as administrator)
winget install -e --id=Microsoft.WSL
- This installs the default Ubuntu distribution, fine for most users (Ubuntu-26.04 is current at the time of writing).
- It also installs a profile inside Windows Terminal, a great terminal emulator for Windows.
- After setting up your Linux user, follow the Linux installation guide to install docker and/or podman.
If WSL is already installed, update it and set version 2
wsl --update
wsl --set-default-version 2
As a non-administrator user
winget install -e --id=Microsoft.WindowsTerminal
winget install -e --id=Docker.DockerCLI
winget install -e --id=RedHat.Podman
winget install "Container Desktop"
Open Container Desktop
Create an automatic connection to your WSL distribution using either docker or podman engines. Choose your preferred one, make it default, and click Connect.
02 Podman and Docker — best experience
Requirements
Ensure all requirements are installed as per the requirements.
Custom WSL
Inside the WSL distribution, follow the Linux installation guide to install both podman and docker container engines.
Best developer experience
Perform all container operations inside the WSL distribution directly — it is just Linux in the end. WSL is the best way to run Linux on Windows.
03 Podman acting as Docker
This is referred to as Compatibility Mode — it should support all docker features, except the docker cli (use podman instead; alias it if you want).
Latest and greatest
Go to the Podman releases page and get the latest Windows installer. Consider:
- Upon installation, podman creates its own WSL distribution, also known as Podman Machine.
- It also sets the
DOCKER_HOSTenvironment variable to point at the podman named pipe.
Easiest (skip if using latest and greatest)
winget install -e --id=RedHat.Podman
04 Docker Desktop alternative
Requirements
Ensure all requirements are installed as per the requirements.
Add docker engine support
Inside the WSL distribution, follow the Linux installation guide to install the docker container engine.
Adding support for the native docker.exe binary
winget install -e --id=Docker.DockerCLI
A restart of your terminal is recommended after installing the CLI tools. Latest docker.exe binaries can also be found at:
- Intel CPUs — download.docker.com/win/static/stable/x86_64
05 Podman — custom installation
Podman engine setup inside WSL
Inside the WSL distribution, follow the Linux installation guide to install the podman container engine.
Container Desktop
Open Container Desktop and create a new Podman engine connection using the WSL host, selecting your distribution of choice.
07 Tips & tricks
Ensure WSL 2 and cgroups v2
To ensure WSL version 2 is set: wsl --set-default-version 2. For the recommended cgroups v2, modify or create the .wslconfig file in %USERPROFILE% with:
[wsl2]
# ...
kernelCommandLine = ipv6.disable=1 cgroup_no_v1=all
After modifying/creating, stop the WSL engine with wsl.exe --shutdown and restart with wsl.exe.
Good to know
Although possible, it is not required to install the Container Desktop application inside WSL.