๐Ÿ‹ Complete Podman Desktop + WSL2 Setup Guide - Replace Docker Desktop for FREE!
#podman#docker#wsl2#containers
kamlesh merugu

kamlesh merugu @kamlesh_merugu

Joined:
May 19, 2025

๐Ÿ‹ Complete Podman Desktop + WSL2 Setup Guide - Replace Docker Desktop for FREE!

Publish Date: Jun 14
2 2

๐Ÿš€ Complete Tutorial: Accessing Podman Desktop Containers from Ubuntu WSL

Ever wished you could seamlessly manage your Podman containers from your Ubuntu WSL terminal while still enjoying the slick UI of Podman Desktop on Windows? ๐Ÿค” You're in luck! This tutorial will guide you through setting up this powerful integration, giving you the best of both worlds. ๐Ÿ’ปโœจ

This is super useful for developers who want to leverage the Linux environment of WSL for their container workflows, while keeping Podman Desktop as their central hub for visual management. Let's dive in! ๐Ÿณ

๐Ÿ“‹ Prerequisites

Before we get started, make sure you have these essentials in place:

  • Podman Desktop installed and happily running on your Windows machine.
  • An Ubuntu WSL distribution already installed and configured.
  • A Podman Machine created in Podman Desktop. (This usually happens automatically during the initial setup. ๐Ÿ‘)

๐Ÿ’ก Overview

Podman Desktop is smart! It sets up a special WSL virtual machine called "Podman Machine" and configures the Windows Podman client to chat with it. However, it doesn't automatically extend this courtesy to your other WSL distributions (like our beloved Ubuntu). Our mission: to bridge this communication gap! ๐ŸŒ‰

Step 1: Access Your Ubuntu WSL Distribution ๐Ÿšช

First things first, let's jump into your Ubuntu WSL session. Open your favorite Windows terminal (Command Prompt, PowerShell, or Windows Terminal) and type:

wsl --distribution Ubuntu
Enter fullscreen mode Exit fullscreen mode

If Ubuntu is your go-to default distribution, a simple wsl will do the trick! ๐Ÿ˜‰

Step 2: Install Podman Remote Client ๐Ÿ“ฅ

Instead of a full-blown Podman installation from Ubuntu's repositories, we're going for the leaner, meaner podman-remote binary. This ensures you're always on the cutting edge with the latest features and best compatibility! โœ‚๏ธ

Download the Latest Podman Remote Binary

Always check the Podman releases page for the absolute latest version.

Then, download and install the binary (remember to replace v5.5.1 with the actual latest version you found!):

wget https://github.com/containers/podman/releases/download/v5.5.1/podman-remote-static-linux_amd64.tar.gz
Enter fullscreen mode Exit fullscreen mode

Configure the Binary ๐Ÿ› ๏ธ

Let's make sure your system knows where to find podman-remote and give it a friendly alias. Edit your .zshrc (or .bashrc if you're using Bash):

echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.zshrc
echo 'alias podman="podman-remote-static-linux_amd64"' >> ~/.zshrc
source ~/.zshrc
Enter fullscreen mode Exit fullscreen mode

Step 3: Identify Your Podman Machine Configuration ๐Ÿ•ต๏ธโ€โ™€๏ธ

Before we connect, we need to know which socket your Podman Desktop is currently using.

Find Available Sockets ๐Ÿ”—

List the available Podman sockets in your WSL distribution:

find /mnt/wsl/podman-sockets/ -name '*.sock'
Enter fullscreen mode Exit fullscreen mode

You should see something like this:

/mnt/wsl/podman-sockets/podman-machine-default/podman-root.sock
/mnt/wsl/podman-sockets/podman-machine-default/podman-user.sock
Enter fullscreen mode Exit fullscreen mode

Identify the Active Socket ๐Ÿ‘€

Now, open a new Command Prompt or PowerShell window on Windows (don't close your WSL terminal yet!). Check which connection Podman Desktop is using:

podman system connection list
Enter fullscreen mode Exit fullscreen mode

Look for the connection marked true in the Default column. The URI will tell you if it's rootful or rootless:

  • Rootful: ssh://root@127.0.0.1:PORT/run/podman/podman.sock (most common, default)
  • Rootless: ssh://user@127.0.0.1:PORT/run/user/1000/podman/podman.sock ### Step 4: Configure the Podman Connection ๐Ÿค

Based on whether your Podman Desktop is using rootful or rootless mode, let's set up the connection!

For Rootful Podman (Default) ๐Ÿ‘‘

If your Podman Desktop is in rootful mode (which is typically the default):

podman system connection add --default podman-machine-default-root unix:///mnt/wsl/podman-sockets/podman-machine-default/podman-root.sock
Enter fullscreen mode Exit fullscreen mode

For Rootless Podman ๐ŸŒฑ

If your Podman Desktop is using rootless mode:

podman system connection add --default podman-machine-default-user unix:///mnt/wsl/podman-sockets/podman-machine-default/podman-user.sock
Enter fullscreen mode Exit fullscreen mode

Step 5: Configure User Permissions ๐Ÿ”’

Your WSL user needs the right permissions to talk to the Podman Machine socket. Add your user to the appropriate group and then exit your WSL session to apply the changes. This step is crucial! ๐Ÿ”‘

sudo usermod --append --groups 10 $(whoami)
exit
Enter fullscreen mode Exit fullscreen mode

Step 6: Test the Connection! โœ…

It's showtime! Restart your WSL session and let's verify everything is working smoothly.

wsl
Enter fullscreen mode Exit fullscreen mode

Verify Group Membership ๐Ÿ‘ฅ

Double-check that your user is now in the correct group:

groups
Enter fullscreen mode Exit fullscreen mode

You should see uucp in the list (this corresponds to group ID 10 for rootful access).

Verify Podman Connection ๐ŸŒ

Confirm that the connection is properly configured:

podman system connection list
Enter fullscreen mode Exit fullscreen mode

Test Podman Version ๐Ÿงช

Now, the moment of truth! Verify that Podman in your WSL can communicate with the remote machine:

podman version
Enter fullscreen mode Exit fullscreen mode

You should see both Client and Server versions, indicating a glorious, successful connection! ๐ŸŽ‰

Test Container Operations ๐Ÿ“ฆ

Let's run a quick test by launching a simple container:

podman run quay.io/podman/hello
podman ps -a --last 1
Enter fullscreen mode Exit fullscreen mode

Voilร ! The container should magically appear in both your WSL terminal output and in Podman Desktop's container list. Synchronization at its finest! ๐Ÿ‘ฏโ€โ™€๏ธ

Step 7: Switching Between Rootful and Rootless (Optional) ๐Ÿ”„

Sometimes you might need to flip between rootful and rootless modes. Here's how:

To Switch to Rootless Mode:

  1. In Windows terminal:

    podman machine set --rootful=false

  2. In WSL:

    podman system connection add --default podman-machine-default-user unix:///mnt/wsl/podman-sockets/podman-machine-default/podman-user.sock

To Switch to Rootful Mode:

  1. In Windows terminal:

    podman machine set --rootful=true

  2. In WSL:

    podman system connection add --default podman-machine-default-root unix:///mnt/wsl/podman-sockets/podman-machine-default/podman-root.sock

๐Ÿ› Troubleshooting Corner

Ran into a snag? Don't worry, we've got you covered with some common fixes!

Permission Denied Errors ๐Ÿšซ

If you're seeing Permission denied errors:

  • Ensure you're in the correct group:

    groups | grep uucp

  • If not, add yourself to the group again and exit/restart:

    sudo usermod --append --groups 10 $(whoami)
exit

  • Restart WSL completely:

    wsl --shutdown

Socket Not Found ๐Ÿ”Œ

If the socket files seem to be playing hide-and-seek:

  • Ensure Podman Desktop is running. ๐Ÿƒโ€โ™€๏ธ
  • Ensure the Podman Machine is started in Podman Desktop.

  • Check if the machine name is different (it might not be podman-machine-default):

    ls /mnt/wsl/podman-sockets/

Connection Refused ๐Ÿ›‘

If you're getting Connection refused errors:

  • Verify Podman Desktop is running.
  • Check that the Podman Machine is started.
  • Try restarting the Podman Machine from Podman Desktop. ๐Ÿ”„

โš™๏ธ Custom Configurations

A couple of notes for more unique setups:

Custom WSL Distribution ๐Ÿง

If you're using a WSL distribution other than Ubuntu, the group names for group ID 10 might be different. You can find the correct group name using:

getent group 10
Enter fullscreen mode Exit fullscreen mode

Custom Podman Machine Name ๐Ÿท๏ธ

If you've been adventurous and created a custom Podman Machine with a different name, simply replace podman-machine-default in the socket paths with your machine's actual name.

โžก๏ธ Next Steps

Congratulations! ๐ŸŽ‰ You've successfully configured your Ubuntu WSL distribution to communicate with Podman Desktop's container engine. Now, the world of containerized development is your oyster within WSL!

You can now:

  • Use all Podman commands directly from your WSL terminal.
  • Manage containers that appear seamlessly in both your WSL and Podman Desktop.
  • Start experimenting with container orchestration tools like Podman Compose.
  • Deeply integrate container workflows into your WSL development environment.

๐ŸŒŸ Summary

You've done it! You've successfully linked your Ubuntu WSL with Podman Desktop, allowing you to enjoy the power of the Podman CLI from within WSL while benefiting from Podman Desktop's excellent graphical interface.

Key takeaways to remember:

  • Always use podman-remote for the latest features and best compatibility.
  • Configure the correct socket path based on your Podman Desktop's rootful/rootless setting.
  • Proper group permissions are essential for socket access.
  • The magic part: Both WSL and Podman Desktop will now show the same containers and images! โœจ

Happy containerizing! ๐Ÿš€

Comments 2 total

  • Sylvain Hittelet
    Sylvain HitteletJun 27, 2025

    Great tutorial! Really helpful to get started with podman.
    You just forgot to explain how to install the software after you download it with

    wget https://github.com/containers/podman/releases/download/v5.5.1/podman-remote-static-linux_amd64.tar.gz
    Enter fullscreen mode Exit fullscreen mode

    I just figured out you simply have to untar it and move it to /usr/local/bin, but that would be a nice addition to make this tutorial complete.

  • JH Laks
    JH LaksJul 16, 2025

    The beginning of this post is really excellent-- kudos.

    However, when executing:
    podman system connection add --default podman-machine-default-root unix:///mnt/wsl/podman-sockets/podman-machine-default/podman-root.sock

    There is a warning:
    time="2025-07-15T17:45:44-07:00" level=warning msg="\"/mnt/wsl/podman-sockets/podman-machine-default/podman-root.sock\" does not exist"

    Did anyone else encounter this? Is there a typo in the command?

    Thanks,
    -J

    P.S. Here is the output from "podman system connection list"

    podman-machine-default ssh://user@127.0.0.1:50825/run/user/1000/podman/podman.sock C:\Users\jhlak.local\share\containers\podman\machine\machine false true
    podman-machine-default-root ssh://root@127.0.0.1:50825/run/podman/podman.sock C:\Users\jhlak.local\share\containers\podman\machine\machine true true

Add comment