Podman Desktop (and Podman) helps you run Linux containers on Windows, backed by Windows Subsystem on Linux (WSL2). Let’s look at the normal installation flow.
As noted in an earlier post, one of the ways to run Linux applications on Windows is to use Podman and Podman Desktop. This post is a collection of screenshots and settings for what you encounter as you install Podman Desktop on a Windows 10 computer. Installed Podman Desktop is relatively pain free, if you follow the guide to set up Podman Desktop on Windows though it needed WSL2 to be enabled. Let’s get started.
1. Download Podman Desktop: You need to download Podman Desktop for Windows from the website. I got the installer since it seemed to be the easiest way.
2. Run the installer. Windows Defender will ask for permission. For now, I left off the public networks setting.
3. The installation finishes quickly and you are brought to the screen below. Select at least to install Podman (the engine that manages the containers). If you don’t, when you start it again, you’ll be told that Podman needs to be set up.
4. When you click on [Next], it asks you if you want to install it. Of course, say [Yes] and it takes you to the Podman Setup.
5. It goes through a few screens and then ends up successfully. Note that I chose to use WSLv2 for the virtualisation provider. It is supposed to have better performance than using Hyper-v. At this point, you can either install WSLv2 yourself (which is what I did) or let the Podman installer handle it for you.
6. I chose to autostart Podman engine when the Podman Desktop is started (since it usually means that I intend to use Podman).
7. Next, Podman needs a default machine that will be used to run the containers. Podman searches if this already exists and if it does not, it will ask you to create one.
8. Fill in the basic settings and let it do its thing.
9. Unfortunately, if you try to specify an image path (as we did in the step above), it will probably fail. The error seems to be due to an unsupported flag.
10. You can’t clear the image path. So, you need to start it again and try again when nothing is provided in the image field. Unfortunately, this also fails since it says that the machine already exists but Podman Desktop can’t find or see it. It says it exists on the hypervisor (i.e., WSLv2).
11. Go to command prompt or Powershell and do this:
❯ wsl --list
Windows Subsystem for Linux Distributions:
Ubuntu (Default)
podman-machine-default
❯ wsl --unregister podman-machine-default
Unregistering.
The operation completed successfully.
❯ wsl --list
Windows Subsystem for Linux Distributions:
Ubuntu (Default)
Basically, we unregistered the podman-machine-default
from WSLv2.
12. Let’s go back to Podman Dekstop and try to create it again.
13. It’s now successful and you’re ready to use Podman.
14. If we go to [Images], we can pull the hello image (that’s shown as a command there). Once you pull it, you’ll see it listed. It is not a container yet – so, we need to “run” it which will create a container from the machine.
15. Clicking on Run (▶) will create a container and run it. You can see it in the Containers tab.
16. It won’t seem to run and will see to exit whenever you click on run. That’s expected. It just outputs some information and then dies. I ran it a couple of times before I realised that that is what it does!
17. You can head on over to a Powershell prompt and also do:
podman container run quay.io/podman/hello
You will see the output on the shell as below. Notet hat this actually creates another container and runs that.
18. You can go back to the [Containers] in Podman Desktop and delete the containers. After that, you can delete the Image that was used (from the [Images] tab).
19. You can also pull something else to try it out. It’s simple and common to try to pull the Nginx web server at this stage, so we do the same. We click on [Pull] in [Images] and type ‘nginx’ – it shows a number of options and you can pick the first one there. Then, [Pull Image].
20. Once it’s done, let’s run it. This shows us the data below – note that it shows that it will be mapped to local port: 9000.
21. This creates and runs a new container and you see the data below in the [Logs] tab of the container.
22. Now, open a web browser and go to http://localhost:9000
and it loads the welcome page from Nginx – cool!
23. You can also use Powershell to view the containers (podman ps
) and also to stop it (podman stop angry_kane
– note the name will be different for you, of course.)
24. You can look at all the logs for the container. Then, delete the container from the desktop, and also the image.
If you run into issues, this may be useful: https://podman-desktop.io/docs/troubleshooting/troubleshooting-podman-on-windows. Also, run podman help
in the terminal for a list of commands to interact with Podman. Finally, you’ll probably also want to set up the docker-compose
extension from the [Extensions] in Podman Desktop.
This post is more for me to remember what I did, and might not help you all that much. If it does, that’s great. I intend to get deeper into these over the next few weeks and I’m sure that I will run into common issues, e.g., with networking, etc. and so I expect to to add more information on this site. Stay tuned!
Feel free to connect with me as @onghu on Twitter or on Mastodon as @onghu@ruby.social or @onghu.com on Bluesky to discuss more, or leave a comment below.