How to Install Podman on Debian 13, 12 and 11

Rootless containers make Podman a practical fit on Debian when you want local container builds and test runs without adding a long-running Docker daemon. To install Podman on Debian, use the default APT package for the local engine, then add only the compatibility or remote-client pieces that match your workflow.

The current Debian path is simpler than many older Podman tutorials suggest. The official Podman installation page points Debian users to the distro package, while the Podman GitHub releases page publishes remote-client tarballs, not full local Linux engine installers.

Install Podman on Debian

Choose a Podman Installation Method on Debian

Debian 13, Debian 12, and Debian 11 all provide Podman from the default main repository, but the packaged branch and companion packages differ by release. Match the package role to the job before installing anything:

Method or Package	Supported Releases	What You Get	Choose It When
Debian APT package	Debian 13, 12, and 11	Full local Podman Engine with APT-managed updates. Current branches are Podman 5.4 on Debian 13, 4.3 on Debian 12, and 3.0 on Debian 11.	You want the recommended local engine for running and building containers.
podman-docker wrapper	Debian 13 and 12	A docker command wrapper that routes Docker-style commands to Podman.	You have scripts that expect the docker command name and you do not need a real Docker daemon.
GitHub release asset	Debian 13, 12, and 11 on x86_64 or arm64	podman-remote only. The Linux release tarballs are remote clients, not complete local engine packages.	You need a client for an existing Podman API service on another host or user socket.
OBS or Kubic repositories	Not recommended for current Debian installs	Older community repository paths that are not needed for Debian 13, 12, or 11.	Avoid this path for normal Debian installs.

If you are installing Podman to run local containers on Debian, choose APT. It installs the engine, runtime, rootless ID helpers, storage support, and networking packages together, and future fixes arrive through normal Debian package updates.

Do not treat podman-remote as a substitute for the APT engine. The remote client can report its version on Debian, but it cannot run local containers unless it connects to an already running Podman API service.

Update Debian Before Installing Podman

Refresh the package index so APT uses current repository metadata:

sudo apt update

These commands use sudo for package installation and system-wide changes. If your account cannot run sudo yet, run the commands as root or follow the guide on how to add a user to sudoers on Debian.

Install Podman with APT on Debian

Install the main Podman package from Debian’s repositories:

sudo apt install podman

APT installs more than one binary because Podman needs a runtime, image tooling, networking helpers, and rootless ID mapping. Debian 13 currently installs modern helpers such as buildah, conmon, crun, netavark, aardvark-dns, passt, slirp4netns, fuse-overlayfs, and uidmap. Debian 12 uses the Podman 4.3 package family with netavark and aardvark-dns, while Debian 11 stays on the older Podman 3.0 and CNI-era networking packages.

Verify Podman on Debian

Check the installed Podman version:

podman --version

Current Debian package output differs by release:

Debian Release	Current Package Branch	Example Version Output
Debian 13 (Trixie)	Podman 5.4	podman version 5.4.2
Debian 12 (Bookworm)	Podman 4.3	podman version 4.3.1
Debian 11 (Bullseye)	Podman 3.0	podman version 3.0.1

Confirm that your normal user can run rootless Podman and that the container storage path sits under your home directory:

podman info --format 'rootless={{.Host.Security.Rootless}} graphDriver={{.Store.GraphDriverName}} graphRoot={{.Store.GraphRoot}}'

A healthy rootless install returns rootless=true. The graph driver can differ by Debian release and host storage state; Debian 13 and Debian 11 can return overlay, while Debian 12 can return vfs. The important success signal is that the graph root belongs to your user, not to root:

rootless=true graphDriver=overlay graphRoot=/home/joshua/.local/share/containers/storage

Run a Podman Hello Container

Run Podman’s hello image from Quay to verify image pulls, rootless execution, storage, and registry access in one short test:

podman run --rm quay.io/podman/hello

Relevant output includes the greeting and project links:

!... Hello Podman World ...!

Project:   https://github.com/containers/podman
Website:   https://podman.io
Desktop:   https://podman-desktop.io
Documents: https://docs.podman.io

Install the Upstream Podman Remote Client from GitHub

The Linux files on the GitHub release page are remote-client tarballs. They do not install the local Podman Engine, networking helpers, storage configuration, or systemd units needed to run containers directly on Debian. Use this method only when you need podman-remote to connect to an existing Podman service.

Install the download and certificate helpers first:

sudo apt install wget ca-certificates

Create a reusable updater helper for the remote client. The helper detects x86_64 or arm64, downloads the current remote-client tarball and matching shasums file, verifies the checksum, then installs the binary as /usr/local/bin/podman-remote. It uses wget for the download and grep to select the matching checksum line.

sudo tee /usr/local/bin/update-podman-remote >/dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

case "$(uname -m)" in
  x86_64) podman_arch=amd64 ;;
  aarch64|arm64) podman_arch=arm64 ;;
  *) echo "Unsupported architecture: $(uname -m)" >&2; exit 1 ;;
esac

workdir="$(mktemp -d)"
trap 'rm -r "$workdir"' EXIT

asset="podman-remote-static-linux_${podman_arch}.tar.gz"
cd "$workdir"

wget -q "https://github.com/containers/podman/releases/latest/download/${asset}"
wget -q "https://github.com/containers/podman/releases/latest/download/shasums"
grep "  ${asset}$" shasums | sha256sum -c -
tar -xzf "$asset"
sudo install -m 0755 "bin/podman-remote-static-linux_${podman_arch}" /usr/local/bin/podman-remote
EOF
sudo chmod 0755 /usr/local/bin/update-podman-remote

Run the helper to install or replace podman-remote:

update-podman-remote

On amd64, the checksum step currently returns:

podman-remote-static-linux_amd64.tar.gz: OK

Verify the remote client binary:

podman-remote --version

Add a connection only after a Podman service exists on the remote host or user socket. Without a reachable service, podman-remote can report its version but cannot run local containers by itself.

Start Using Podman on Debian

Learn Basic Podman Commands on Debian

Podman uses Docker-style command patterns, but rootless mode keeps containers, images, and volumes under the current user’s container storage. A container started as your normal user is separate from any container started later with sudo podman, so stay consistent unless you specifically need root-owned containers.

Use fully qualified image names in examples and scripts. For example, docker.io/library/nginx:alpine names the registry, namespace, image, and tag directly, which avoids short-name prompts or registry ambiguity on fresh systems.

Task	Command	What It Checks or Changes
Search a registry	podman search nginx	Looks for matching images before you pull one.
Pull an image	podman pull docker.io/library/nginx:alpine	Downloads the image into your rootless image store.
List local images	podman images	Shows images available to the current user.
List running containers	podman ps	Shows only containers that are currently running.
List all containers	podman ps -a	Shows running and stopped containers.
View container logs	podman logs CONTAINER	Prints stdout and stderr from a named container.
Stop a container	podman stop CONTAINER	Gracefully stops a running container.
Remove a container	podman rm CONTAINER	Deletes a stopped container while keeping its image.
Remove an image	podman image rm IMAGE	Deletes an image when no container still depends on it.

Use podman --help or podman COMMAND --help when you need flags for a specific action. The next two workflows use these basics in a practical Nginx container and a small custom image build.

Run a Rootless Nginx Container

This example runs Nginx without sudo and maps container port 80 to host port 8080. Rootless users can bind high ports such as 8080 without changing privileged-port settings.

podman run -d --name lc-nginx -p 8080:80 docker.io/library/nginx:alpine

Confirm the container name and port mapping:

podman ps --filter name=lc-nginx --format 'name={{.Names}} ports={{.Ports}}'

name=lc-nginx ports=0.0.0.0:8080->80/tcp

Install wget only if the HTTP probe command is missing:

command -v wget || sudo apt install wget

Check the web response from the host:

wget -qO- http://127.0.0.1:8080 | grep -m1 '<title>'

<title>Welcome to nginx!</title>

Remove the demo container when you are done:

podman rm -f lc-nginx

This port mapping listens on the Debian host. If you want other machines to reach that port, configure your firewall deliberately instead of opening broad access by accident; the guide to install UFW on Debian covers the local firewall tool most Debian users choose first.

Build a Small Podman Image

Podman builds images from a Containerfile or Dockerfile-style file. Create a tiny Nginx image that replaces the default page with one custom line:

mkdir -p ~/podman-demo
cd ~/podman-demo
printf '%s\n' 'Hello from Podman on Debian' > index.html

Create the Containerfile. This file tells Podman to use the official Nginx Alpine image and copy your custom page into the web root:

cat > Containerfile <<'EOF'
FROM docker.io/library/nginx:alpine
COPY index.html /usr/share/nginx/html/index.html
EOF

Build the image:

podman build -t localhost/lc-podman-demo:latest .

Run the image as a container on host port 8081. Using a different host port keeps this demo separate from the earlier Nginx test that used 8080:

podman run -d --name lc-demo -p 8081:80 localhost/lc-podman-demo:latest

Request the page from the host to verify that the container is serving your custom file:

wget -qO- http://127.0.0.1:8081

Hello from Podman on Debian

Clean up the demo container and image:

podman rm -f lc-demo
podman image rm localhost/lc-podman-demo:latest

The next command deletes only the demo directory created in this section. Keep it if you changed the files for your own project.

rm -r ~/podman-demo

Use Docker-Compatible Podman Commands

The optional podman-docker package makes the docker command call Podman. Debian 13 and Debian 12 provide this wrapper in the default repository; Debian 11 does not, so Bullseye users should keep using the podman command name instead of creating an untracked manual symlink.

Check whether Docker Engine already owns the command name:

command -v docker

No output means the command name is currently unused. If the command already points to Docker Engine, leave it alone unless you intentionally want Podman to replace that workflow. For a real Docker daemon, use the separate guide to install Docker on Debian.

On Debian 13 or Debian 12, install the wrapper without pulling unrelated recommended packages:

sudo apt install --no-install-recommends podman-docker

Verify that docker now resolves to Podman:

docker --version

Debian 13 currently returns:

Emulate Docker CLI using podman. Create /etc/containers/nodocker to quiet msg.
podman version 5.4.2

Run the hello test through the Docker-compatible command name so you verify routing, image pulls, and rootless execution through the wrapper:

docker run --rm quay.io/podman/hello

The first Docker-compatible run prints Podman’s emulation notice before the container output:

Emulate Docker CLI using podman. Create /etc/containers/nodocker to quiet msg.
!... Hello Podman World ...!

Create the marker file after you understand the compatibility layer and want to hide that notice:

sudo touch /etc/containers/nodocker

Manage the Podman User Socket on Debian

Normal podman run, podman build, and podman ps commands do not need a daemon. Enable the user socket only when another tool needs a Docker-compatible API endpoint for your rootless containers.

systemctl --user enable --now podman.socket

Confirm that the socket is active:

systemctl --user is-active podman.socket

active

Confirm that the socket file exists under the current user’s runtime directory:

test -n "${XDG_RUNTIME_DIR:-}" && test -S "${XDG_RUNTIME_DIR}/podman/podman.sock" && echo "Podman user socket is ready"

Podman user socket is ready

Tools that accept Docker socket URLs can use unix://${XDG_RUNTIME_DIR}/podman/podman.sock for the current login session. Use the system-wide Podman socket only for root-owned API workflows, because that socket exposes root’s Podman storage instead of your rootless containers.

Disable the user socket later if you no longer need API access:

systemctl --user disable --now podman.socket

Manage Podman Updates and Removal on Debian

Update Podman by Installation Method

APT-installed Podman updates through Debian’s normal package flow. Upgrade the local Podman engine with:

sudo apt update
sudo apt install --only-upgrade podman

On Debian 13 or Debian 12, upgrade the Docker-compatible wrapper separately if you installed it:

sudo apt install --only-upgrade podman-docker

For the GitHub remote client, rerun the updater helper. The helper resolves the current release through GitHub’s latest-release redirect and verifies the new tarball before replacing /usr/local/bin/podman-remote:

update-podman-remote

Remove Podman Packages and Data

If you enabled the user socket, stop it before removing Podman:

systemctl --user disable --now podman.socket

Remove the local Podman engine package:

sudo apt remove podman

On Debian 13 or Debian 12, remove the Docker-compatible wrapper if you installed it:

sudo apt remove podman-docker

Confirm neither package remains installed:

dpkg -l podman podman-docker 2>/dev/null | grep '^ii' || true

No output means APT no longer has either package installed. Preview orphaned dependencies before removing them, because container helper packages can also be used by Buildah, Skopeo, or other tooling:

sudo apt autoremove --dry-run

Continue only if the preview lists packages you no longer need:

sudo apt autoremove

Remove the GitHub remote client binary and updater helper if you installed them:

sudo rm -f /usr/local/bin/podman-remote /usr/local/bin/update-podman-remote
hash -r
command -v podman-remote || echo "podman-remote removed"
command -v update-podman-remote || echo "update-podman-remote removed"

podman-remote removed
update-podman-remote removed

The following commands permanently delete local container images, containers, volumes, registry settings, and caches for the selected scope. Export anything you need before deleting these paths.

Inspect the current user’s container data paths before deleting them. No output means none of the common paths exist for that account:

for path in ~/.local/share/containers ~/.config/containers ~/.cache/containers; do
  [ -e "$path" ] && printf '%s\n' "$path"
done

Remove the listed rootless container data only when you no longer need those images, containers, volumes, or registry settings:

rm -rf ~/.local/share/containers ~/.config/containers ~/.cache/containers

Inspect root-owned container data only if you ran containers with sudo podman:

sudo find /var/lib/containers -maxdepth 1 -mindepth 1 -print 2>/dev/null

Remove the root-owned container store only when the listed files belong to containers you no longer need:

sudo rm -rf /var/lib/containers

Troubleshoot Podman on Debian

APT Cannot Locate the Podman Package

Debian 13, Debian 12, and Debian 11 provide podman from the default main repository. If sudo apt install podman returns this error, the package index is stale, the Debian base source is incomplete, or the system is not using one of those supported releases:

E: Unable to locate package podman

Check your release and Podman candidate first:

. /etc/os-release
printf '%s\n' "$VERSION_CODENAME"
apt-cache policy podman

If the candidate is still (none) after refreshing APT, repair your Debian base sources before adding third-party repositories:

sudo apt update
apt-cache policy podman

Avoid old OBS or Kubic repository instructions for normal Debian installs. Current Debian releases already package the local engine, and stale third-party container repositories can create source conflicts or older package candidates.

Debian 11 Cannot Install podman-docker

Debian 11 provides the podman package but not the podman-docker wrapper from its default repositories. If Bullseye returns this error, keep using the podman command name or move the wrapper workflow to Debian 12 or 13:

E: Unable to locate package podman-docker

Confirm the package state with:

apt-cache policy podman-docker

Rootless Podman Reports Missing newuidmap

This error appears when Podman needs subordinate ID helpers but newuidmap is missing from the installed package set or your account lacks subordinate ID ranges:

Error: command required for rootless mode with multiple IDs: exec: "newuidmap": executable file not found in $PATH

Install uidmap first:

sudo apt install uidmap

Then confirm your account has subordinate user and group ID ranges:

command -v newuidmap newgidmap
grep "^${USER}:" /etc/subuid /etc/subgid

Example output shows one ID range in each file:

/etc/subuid:joshua:100000:65536
/etc/subgid:joshua:100000:65536

If the ID files do not list your user, add a subordinate ID range:

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 "$USER"

Sign out and back in so your session sees the new range, then migrate Podman’s rootless storage metadata:

podman system migrate

User Socket Commands Cannot Connect to the User Bus

If systemctl --user enable --now podman.socket cannot connect to the user bus, make sure you are running it as your normal user, not with sudo, and confirm that the login session has a runtime directory:

printf '%s\n' "${XDG_RUNTIME_DIR:-not set}"
systemctl --user status podman.socket

On a normal logged-in session, XDG_RUNTIME_DIR should point to a path such as /run/user/1000. Log in again through SSH or the desktop session, then retry the user socket command.

GitHub podman-remote Cannot Run Local Containers

The static Linux asset from GitHub is a remote client. If podman-remote run cannot connect, that does not mean the tarball is broken; it means no Podman API service is available for the client to use. Install the local engine with APT or add a remote connection to an existing service.

podman-remote system connection list

An empty connection list means the remote client has nowhere to send container commands yet.

Docker Commands Still Use Docker Engine

If docker --version still reports Docker Engine after installing podman-docker on Debian 13 or 12, another package or custom path entry owns the docker command. Check the active command path and package owner:

command -v docker
dpkg -S "$(command -v docker)"

Keep Docker Engine if your workflow needs the Docker daemon, Docker’s Compose plugin, Buildx, or Docker-specific socket behavior. Use podman-docker only when you want Docker-compatible command names to call Podman instead.

Conclusion

Podman is running on Debian with rootless storage, a verified container workflow, and clear boundaries for the Docker-compatible wrapper and upstream remote client. Keep using Podman when daemonless containers fit the job; switch to Docker on Debian only when a real Docker daemon is required.