Skip to main content

How to run Podman on Windows with WSL2

Want to run Podman on Windows 10? You can, thanks to the latest Windows Subsystem for Linux (WSL) 2.0 implementation.
Image
Seal swimming at aquarium

With the latest Windows Subsystem for Linux (WSL) 2.0 implementation, Podman now works out of the box. Minor changes to a configuration file make Podman more convenient to use. In the upcoming sections, I will document how I ran Podman under WSL2 and what configurations I changed to make things work smoothly.

At this time of this writing, WSL2 is only available as part of the Windows Insider program. As their documentation notes, you need to have at least Windows 10 build 18917. To set up WSL2, I followed Microsoft’s instructions.

Once I had the WSL environment installed, I then installed a Linux distribution from the Microsoft store. In this case, I chose to install Ubuntu.

[Editor's Note: Red Hat distributions are not currently officially available in WSL.]

Image
The results of cat /etc/os-release after installing Ubuntu.

Add the Podman PPA and install Podman

The easiest way to begin the installation of Podman on Ubuntu is to use the Kubic project as described in the installation documentation. You can easily add this package to your Ubuntu distribution:

. /etc/os-release
sudo sh -c "echo 'deb http://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/stable/x${NAME}_${VERSION_ID}/ /' > /etc/apt/sources.list.d/devel:kubic:libcontainers:stable.list"
wget -nv https://download.opensuse.org/repositories/devel:kubic:libcontainers:stable/x${NAME}_${VERSION_ID}/Release.key -O Release.key
sudo apt-key add - < Release.key
sudo apt-get update -qq
sudo apt-get -qq -y install podman
sudo mkdir -p /etc/containers
echo -e "[registries.search]\nregistries = ['docker.io', 'quay.io']" | sudo tee /etc/containers/registries.conf

Because of WSL2’s unique environment, I recommend making changes to Podman’s configuration file. Otherwise, you will need to pass extra configuration options to each podman command. If you prefer this approach, you must pass the following to each incantation of podman:

--cgroup-manager cgroupfs --event-logger file

The two sections below describe how to make these changes permanent for rootless and privileged Podman users.

Rootless configuration file changes

If you plan to run podman as a non-root user, you should start with a simple podman command like:

$ podman info 

This action will create the Podman configuration file $HOME/.config/containers/libpod.conf. Simply edit this file and change the value of events_logger to <file>.

Rootfull configuration file changes

If you wish to run podman as a privileged user, you should first copy the Podman configuration file to /etc/containers/.

$ sudo cp /usr/share/containers/libpod.conf /etc/containers

Now, edit the version in /etc/containers and change the value of cgroup_manager to cgroupfs. Then, uncomment the line for the events_logger key and change the value to <file>.

The following is a simple diff of the changes:

27c27
< cgroup_manager = "systemd"
---
> cgroup_manager = "cgroupfs"
109c109
< # events_logger = "journald"
---
> events_logger = "file

Gotchas

Remember that WSL2 is still an experimental environment, and as such, not everything in Podman will work correctly. For example, I made changes to disable SystemD-related features in the Podman configuration file. I have not tested the ability to use SystemD in a WSL distribution for controlling containers. SystemD is also used by Podman for container health checks. This feature has also not been tested.

What to read next

Topics:   Containers  
Author’s photo

Brent Baude

Brent is a Principle Software Engineer at Red Hat and leads the Container Runtimes team which includes things like Podman and Buildah. He is a maintainer of Podman upstream and a major contributor as well. More about me

Related Content

OUR BEST CONTENT, DELIVERED TO YOUR INBOX