Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

Installing Podman on Linux, macOS and Windows

Install Podman with your package manager, set up podman machine on macOS and Windows, check the install with podman info, and fix the first common problems.

Installing Podman is different depending on your system, because containers need a Linux kernel. On Linux you install a normal package and you are done. On macOS and Windows, the Podman program on your desktop talks to a small Linux virtual machine that Podman creates and manages for you. After installing, a couple of commands tell you whether everything works.

This lesson covers all three systems, the first checks to run, and the small pieces of configuration that you may need before your first container.

Installing on Linux

Podman is in the default repositories of most distributions. Use your package manager:

Terminal
# Fedora, RHEL, CentOS Stream, Rocky, Alma
sudo dnf install podman

# Debian, Ubuntu
sudo apt update
sudo apt install podman

# Arch Linux
sudo pacman -S podman

# openSUSE
sudo zypper install podman

Distribution packages can lag a few releases behind upstream, which matters for newer features such as the latest Quadlet options or Podman 5 networking. Check your version with podman --version; this course mentions when a feature needs a recent release.

Podman pulls in its helpers as dependencies: crun (the OCI runtime), conmon, netavark and aardvark-dns (networking), and for rootless networking pasta (from the passt package) or the older slirp4netns. You normally do not install these by hand.

Rootless prerequisites on Linux

Rootless containers need a range of extra user IDs for your account. They are listed in two files:

Terminal
grep "$USER" /etc/subuid /etc/subgid

A line such as alice:100000:65536 means the user alice may use 65,536 IDs starting at 100000. Most distributions create these lines when the user is created. If they are missing, an administrator can add them:

Terminal
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 "$USER"
podman system migrate

The podman system migrate command makes Podman pick up the new mapping. You also need the helper programs newuidmap and newgidmap (package shadow-utils or uidmap), which Podman uses to apply the mapping. Rootless and User Namespaces explains these numbers.

Installing on macOS

On a Mac the easiest way is Homebrew. There is also an installer on the Podman website and a graphical app called Podman Desktop, which uses the same engine.

Terminal
brew install podman
podman machine init
podman machine start

podman machine init downloads a Linux image and creates a virtual machine. podman machine start boots it. The podman command you type on macOS is a remote client: it sends your request to Podman running inside that machine, and it forwards ports and (some) folders to your Mac. The first start takes a minute or two.

Installing on Windows

On Windows, Podman uses Windows Subsystem for Linux (WSL 2) by default, or Hyper-V if you choose it. Install WSL first, then Podman:

POWERSHELL
wsl --install
winget install RedHat.Podman
podman machine init
podman machine start

You can also install Podman Desktop, which adds a graphical dashboard on top. After a reboot (WSL asks for one the first time), the commands above give you a working podman in PowerShell or a terminal. Use podman machine list to see the machine and whether it is running.

System Where containers really run Setup step
Linux directly on your kernel none
macOS a managed Linux VM podman machine init and start
Windows a WSL 2 (or Hyper-V) VM podman machine init and start

Checking the installation

Run these three commands. They should work as a normal user.

Terminal
podman --version
podman info
podman run --rm quay.io/podman/hello

podman info prints a long report: the version, the OCI runtime, the storage location, whether you are rootless, the network backend, and how many images you have. Look for rootless: true on Linux as a normal user, and a store section that shows where images live. The last command pulls a tiny image, runs it, prints a greeting, and removes the container because of --rm.

If podman info fails on macOS or Windows with a connection error, the virtual machine is not running. Run podman machine list, then podman machine start.

Handy first configuration

Podman reads configuration from three small families of files. You do not need to edit them yet, but it helps to know where they are.

File What it controls
containers.conf engine defaults: runtime, log driver, default capabilities, network backend
storage.conf where and how images and containers are stored
registries.conf which registries to search and short-name behavior

System-wide copies live under /usr/share/containers and /etc/containers. A rootless user overrides them in ~/.config/containers/. The files use the TOML format, and a later file wins over an earlier one.

Here is a stand-in that shows how that "later wins" layering works, with a few made-up settings. It is plain JavaScript, not Podman, and the setting names are examples.

JS Stand-in: layered configuration

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Picking the right install command

Because the commands differ per system, here is a little helper that returns the install steps for the system you name. Again, this is a stand-in that only prints the commands taught above.

JS Stand-in: install steps lookup

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common first problems

  • "cannot find newuidmap": install uidmap (Debian/Ubuntu) or shadow-utils (Fedora).
  • "no subuid ranges found": add ranges as shown above, then podman system migrate.
  • Pulling stalls on Windows or macOS: the virtual machine may be out of disk space. podman machine set --disk-size 100 resizes it (the machine must be stopped).
  • Old version from the distribution: on LTS releases, check the Podman documentation for a newer package source.
  • Mixing rootless and sudo: images pulled as your user are invisible to sudo podman, because each has its own storage. This is expected, not a bug.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. On macOS and Windows, where do Podman containers actually run?

    Containers need a Linux kernel. Podman creates and manages a small Linux VM, and the local podman command acts as a remote client.
  2. 2. Which files tell Podman how many extra user IDs your account may use for rootless containers?

    subuid and subgid hold the ranges of subordinate user and group IDs. Rootless Podman maps container IDs into them.
  3. 3. You pulled an image as a normal user, but sudo podman images does not show it. Why?

    Each user, including root, has its own image and container storage, so nothing is shared between rootless and rootful runs.
  4. 4. Where would you place your personal overrides for containers.conf as a rootless user?

    User-level configuration lives in ~/.config/containers/ and takes precedence over the system-wide files.

Summary

  • On Linux, install Podman with your distribution's package manager.
  • On macOS and Windows, install it, then run podman machine init and podman machine start.
  • Rootless mode needs /etc/subuid and /etc/subgid entries and newuidmap/newgidmap.
  • podman --version, podman info and quay.io/podman/hello check that everything works.
  • Configuration lives in containers.conf, storage.conf and registries.conf, with user files overriding system ones.
  • Rootless and rootful Podman do not share images or containers.

Next: Your First Container