Run docker-compose against Podman via the Docker-compatible socket
Every Podman mechanic in this record holds, and I confirmed each against the Arch Podman wiki fetched as raw wikitext: the podman.socket user unit plus the DOCKER_HOST export (lines 222 to 224, and usr/lib/systemd/user/podman.socket is in podman 6.1.1-1's file list), podman compose as a thin wrapper with docker-compose taking precedence and PODMAN_COMPOSE_PROVIDER as the override (line 220), DOCKER_BUILDKIT=0 (line 229), the unqualified-search-registries drop-in under /etc/containers/registries.conf.d/ (lines 33 to 36 and 459 to 464, including the exact short-name error), podman-docker as the docker shim (line 21), lingering (line 418), and the record's danger about compose networks surviving podman compose down (line 555). I also checked that the BuildKit advice is not stale: docker-compose here is the Go plugin, not the old Python tool (Arch package docker-compose 5.5.0-1 with url https://www.docker.com/, shipping both /usr/bin/docker-compose and /usr/lib/docker/cli-plugins/docker-compose, and docker-compose version prints Docker Compose version 5.5.0), and that Go Compose still reads the variable: DOCKER_BUILDKIT appears 7 times in the binary's string table, pkg/api/context.go documents BuildKitEnabled() as checking it, and pkg/compose/build_classic.go still exists upstream. So I did not correct that. Three real defects, all Omarchy-specific. First, ~/.config/uwsm/env is the Omarchy 3 path. Omarchy 4 retires it: /usr/bin/omarchy-upgrade-to-quattro copies it to a backup, migrates custom lines into ~/.config/uwsm/env.d/99-omarchy-upgrade-env, then deletes the live file with the comment never keep the active file at line 1957, and /usr/share/omarchy/default/uwsm/env.d/10-omarchy tells users to override in ~/.config/uwsm/default or preferably, ~/.config/uwsm/env.d/*. The quattro tree confirms it: gh api repos/omacom/omarchy/git/trees/quattro?recursive=1 lists only default/uwsm/default and default/uwsm/env.d/10-omarchy and no config/uwsm/env. uwsm 0.26.7's own README (lines 639 to 643) does still source uwsm/env, so the old path works today, which is why this is a correction rather than a reject. Second, Omarchy 4 does not ship Podman at all: pacman -Q podman fails on this workstation and podman appears in neither /usr/share/omarchy/install/omarchy-base.packages nor omarchy-other.packages, which carry docker, docker-buildx, docker-compose, lazydocker and ufw-docker instead. Third and most costly for a reader, the record's headline error string sends an Omarchy user to the wrong cause. /usr/share/omarchy/install/config/docker.sh deliberately leaves the install user out of the docker group as root-equivalent, install/config/enable-services.sh enables docker.socket, and I confirmed locally that getent group docker is empty, /var/run/docker.sock is srw-rw---- 1 root docker, and docker ps as the unprivileged user returns permission denied while trying to connect to the docker API at unix:///var/run/docker.sock (docker 1:29.7.2-1). I split the symptom so both strings are matchable and added the Omarchy branch with omarchy-setup-security-sudoless-docker, whose own script text supplied the root-equivalence warning I put in danger. I also fixed verify, which claimed with no Docker daemon installed, a false premise on stock Omarchy 4, and changed the two bare sudo pacman -S lines to -Syu per the partial-upgrade rule. sources_remove drops https://raw.githubusercontent.com/basecamp/omarchy/master/config/uwsm/env. It still returns HTTP 200, so it resolves, but master is the Omarchy 3 tree and it does not support the Omarchy 4 claim the record now makes. Frequency lowered from common to occasional because Podman ships by default on none of the distros in applies_to, so this is a problem only for users who chose Podman. Severity left at medium: it blocks work and loses nothing. Not exercised: I have no sudo, so I did not enable podman.socket, install podman, write any registries drop-in, join the docker group, or start a container. The Branch B commands are read from the Arch wiki and the package contents, not observed running.
Corrected by hand on 2026-09-11 after the merge: this verdict's own fix wrote sudo pacman -Syu podman and sudo pacman -Syu podman-docker, which carry both a sync and a sysupgrade flag and are therefore exactly what omarchy-update-pacman-guard aborts, in the same fix that explains the guard. Both are now pacman -S --needed. Found by lint_corpus.py on the audit's output, which is what that lint is for.
omarchy-setup-security-sudoless-docker adds you to the docker group, and that group is equivalent to passwordless root: anything running as your user can then run docker run -v /:/host alpine and rewrite the whole host as root with no prompt. Omarchy leaves you out of it by default for exactly that reason, and the script prints the same warning before it acts. On the Podman side, podman-compose has known compatibility gaps with real compose files, so do not assume a working docker-compose.yml behaves identically. Networks created by a compose project are often not removed by podman compose down, so check podman network ls and clean up with podman network rm rather than assuming the environment is gone. podman-docker installs its own /usr/bin/docker, so it conflicts with the docker package Omarchy ships and pacman will ask you to remove one.
Symptom
docker compose up or docker-compose up cannot reach a daemon. Two failures look alike and have different causes, so read the exact wording first.
Podman installed and no Docker daemon running:
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Stock Omarchy 4, where Docker IS installed and docker.socket IS enabled, but the user is deliberately not in the docker group:
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock
Or podman compose runs but builds fail with buildkit errors, or an image reference fails with short-name "nginx" did not resolve to an alias and no unqualified-search-registries are defined in "/etc/containers/registries.conf".
Cause
Two separate causes behind similar text. On stock Omarchy 4 the daemon is there and the user is not allowed to talk to it: /usr/share/omarchy/install/config/docker.sh deliberately leaves the install user out of the docker group because that group is root-equivalent, and /var/run/docker.sock is srw-rw---- root docker, so the client gets a permission error rather than a missing daemon. Omarchy does not ship Podman at all, so a Podman setup on Omarchy is something the user installed. When Podman is the runtime, the cause is that Podman is daemonless, so nothing listens on a Docker socket until Podman's REST API socket is enabled. docker-compose speaks only to $DOCKER_HOST, and podman compose is a thin wrapper that shells out to whichever compose provider is installed. Separately, Arch's podman ships with no search registries configured, so unqualified image names never resolve.
Fix
First decide which problem you have, because the answers do not overlap.
Branch A, stock Omarchy 4 with Docker. Omarchy installs docker, docker-buildx and docker-compose and enables docker.socket, but leaves you out of the docker group on purpose, so Docker access goes through a prompt. Either elevate per command:
sudo docker compose up
or opt in to the group, behind Omarchy's own warning, and reboot:
omarchy-setup-security-sudoless-docker # Setup > Security > Sudoless Docker
Read the danger note before you do that. To undo it:
omarchy-remove-security-sudoless-docker
Branch B, Podman instead of Docker. Podman is not part of Omarchy, so install it yourself first:
sudo pacman -S --needed podman
Enable Podman's Docker-compatible socket as a user unit and point the client at it:
systemctl --user enable --now podman.socket
systemctl --user status podman.socket
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
docker compose version
Make it permanent for shells, user units and GUI apps. On Omarchy 4 the graphical session environment is loaded by uwsm from env.d drop-ins, and the user's file goes in ~/.config/uwsm/env.d/:
mkdir -p ~/.config/uwsm/env.d
cat > ~/.config/uwsm/env.d/50-podman-docker-host <<'EOF'
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
EOF
Do not use ~/.config/uwsm/env. That was the Omarchy 3 path. uwsm still sources it, but Omarchy 4's upgrade tool retires it: omarchy-upgrade-to-quattro migrates custom lines into ~/.config/uwsm/env.d/99-omarchy-upgrade-env and then deletes the file. Log out and back in for the change to take effect.
And for systemd user units:
mkdir -p ~/.config/environment.d
printf 'DOCKER_HOST=unix://%%t/podman/podman.sock\n' > ~/.config/environment.d/podman-docker.conf
BuildKit is not supported through the Podman socket, so turn it off:
export DOCKER_BUILDKIT=0
Configure search registries so plain nginx and archlinux resolve like they do with Docker:
sudo mkdir -p /etc/containers/registries.conf.d
sudo tee /etc/containers/registries.conf.d/10-unqualified-search-registries.conf >/dev/null <<'EOF'
unqualified-search-registries = ["docker.io"]
EOF
If you want the docker command itself to be Podman, install the shim. Note it conflicts with a real Docker install, so remove docker first if Omarchy put it there:
sudo pacman -S --needed podman-docker
To pick which compose implementation podman compose uses when both are installed (docker-compose wins by default):
export PODMAN_COMPOSE_PROVIDER=podman-compose
For containers to survive logout, enable lingering:
loginctl enable-linger
Verify
Branch A: sudo docker compose version and sudo docker ps work, or after omarchy-setup-security-sudoless-docker and a reboot the same two work with no sudo and id -nG | tr ' ' '\n' | grep -w docker matches. Branch B: with Docker's daemon absent or stopped, docker compose version and docker ps both work against $DOCKER_HOST, podman ps shows the same containers docker ps does, and systemctl --user is-active podman.socket reports active.
Sources
- https://wiki.archlinux.org/title/Podman
- https://wiki.archlinux.org/title/Systemd/User
- https://archlinux.org/packages/extra/x86_64/podman/
- https://archlinux.org/packages/extra/x86_64/podman-docker/
- https://archlinux.org/packages/extra/any/podman-compose/
- https://archlinux.org/packages/extra/x86_64/docker-compose/
- https://raw.githubusercontent.com/docker/compose/main/pkg/api/context.go
- https://raw.githubusercontent.com/docker/compose/main/pkg/compose/build_classic.go
- https://github.com/omacom/omarchy/tree/quattro/default/uwsm/env.d