Using podman-compose in a DevContainer

You want a Compose-style multi-service devcontainer but you're on Podman, not Docker. This page wires the devcontainer to podman-compose (or Podman's Docker-compatible Compose provider), so your app and its backing services run rootless with the same networking and health-gating you'd get on Docker.

Prerequisites

You need rootless Podman and podman-compose (or the compose provider) installed.

  • Rootless Podman working.
  • podman-compose installed, or Podman's Compose provider enabled.
  • A Compose file and a devcontainer that names its service.

podman-compose prerequisitesYou need podman-compose, the Compose path set, a shared network, and a workspace service.podman-composeinstalleddockerComposePathset to itBridge netsharedAttachworkspace service

Step-by-Step Implementation

  1. Point the tooling at podman-compose.
{
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "remoteUser": "vscode"
}
  1. Set the editor's compose path to podman-compose.
"dev.containers.dockerComposePath": "podman-compose"
  1. Share a network so services resolve by name.
services:
  app: { networks: [devnet] }
  db: { image: postgres:16-alpine, networks: [devnet] }
networks: { devnet: {} }
  1. Verify the app reaches the service by name.
devcontainer exec --workspace-folder . -- getent hosts db

podman-compose modelpodman-compose brings up services rootless on a shared network the workspace attaches to.podman-composebrings services up rootlessShared bridgename resolutionHealth checksgate startup orderAttach pointworkspace service

Common Pitfalls

Podman Compose issues are a wrong provider path or missing shared network.

Compose triageA triage path from a failing rootless stack to a working one.Does the stack come up with podman?NOSet the compose provider pathDo services resolve by name?YESAll on one shared bridgeRootless multi-service works

SymptomRoot CauseRemediation
Compose commands failDocker compose path assumedSet dockerComposePath to podman-compose
Services can't resolve namesNot on a shared networkPut services on one bridge network
Ports not reachableRootless low-port limitUse ports above 1024
App starts before DBNo health gateAdd healthcheck + depends_on

Conclusion

A multi-service devcontainer runs fine on Podman: point the tooling at podman-compose, put services on a shared bridge so names resolve, and gate startup with health checks. The Compose model is identical — only the provider underneath changes.

Same vs differentThe Compose model is unchanged; only the provider and rootless caveats differ.Same as DockerCompose fileService networkingHealth checksPodman-specificCompose provider pathRootless portskeep-id ownership

FAQ

Can I use a docker-compose.yml unchanged with Podman? Mostly yes. Point the tooling at podman-compose (or Podman's Docker-compatible Compose provider) and the same Compose file brings the stack up rootless. Watch for rootless port and ownership differences, but the service and network definitions carry over.

Why can't my services find each other? They need to share a user-defined bridge network for name resolution, exactly as on Docker. Put every service that must communicate on one network and address peers by service name.

Do health checks work the same? Yes — declare healthcheck on services and gate the workspace with depends_on: condition: service_healthy. Podman honours the same Compose health semantics, so startup ordering behaves as it does on Docker.