Podman

Podman can run rootless containers and be a drop-in replacement for Docker

Setup

❄︎ /etc/nixos/configuration.nix

virtualisation.podman = {
  enable = true;
  dockerCompat = true; # Creates a symlink from docker to podman
  defaultNetwork.settings.dns_enabled = true; # Required for containers under podman-compose to be able to talk to each other.
};

users.users.<USERNAME> = { # replace `<USERNAME>` with the actual username
  extraGroups = [
    "podman"
  ];
};

🛡︎︎

Security information: Beware that the podman group membership is effectively equivalent to being root, just like with Docker!
Consider using rootless podman.

A reboot or re-login might be required for the permissions to take effect after applying changes

Tips and tricks

podman compose

podman compose is a thin wrapper around an external compose provider such as docker-compose or podman-compose. This means that podman compose is executing another tool that implements the compose functionality but sets up the environment in a way to let the compose provider communicate transparently with the local Podman socket. The specified options as well as the command and argument are passed directly to the compose provider.

The default compose providers are docker-compose and podman-compose. If installed, docker-compose takes precedence since it is the original implementation of the Compose specification.

To change the default behavior or have a custom installation path for your provider of choice:

{
  services.podman.settings.containers = { compose_providers = ["/path/to/provider"] };
}

You may also set the PODMAN_COMPOSE_PROVIDER environment variable:

PODMAN_COMPOSE_PROVIDER="/path/to/provider" podman compose up -d

or:

{
  environment.sessionVariables = {
    PODMAN_COMPOSE_PROVIDER = "/path/to/provider";
  };
}

By default, podman compose will emit a warning saying that it executes an external command. This warning can be disabled by setting compose_warning_logs to false in services.podman.settings.containers or setting the PODMAN_COMPOSE_WARNING_LOGS environment variable to false.

{
  services.podman.settings.containers = {
    compose_providers = ["/path/to/provider"];
    compose_warning_logs = false;
  };
}

{
  environment.sessionVariables = {
    PODMAN_COMPOSE_PROVIDER = "/path/to/provider";
    PODMAN_COMPOSE_WARNING_LOGS = false;
  };
}

With ZFS

Rootless can't use ZFS directly but the overlay needs POSIX ACL enabled for the underlying ZFS filesystem, ie., acltype=posixacl

Best to mount a dataset under /var/lib/containers/storage with property acltype=posixacl.

Within nix-shell

From https://gist.github.com/adisbladis/187204cb772800489ee3dac4acdd9947 :

❄︎ podman-shell.nix

{ pkgs ? import <nixpkgs> {} }:

let

  # To use this shell.nix on NixOS your user needs to be configured as such:
  # users.extraUsers.adisbladis = {
  #   subUidRanges = [{ startUid = 100000; count = 65536; }];
  #   subGidRanges = [{ startGid = 100000; count = 65536; }];
  # };

  # Provides a script that copies required files to ~/
  podmanSetupScript = let
    registriesConf = pkgs.writeText "registries.conf" ''
      [registries.search]
      registries = ['docker.io']

      [registries.block]
      registries = []
    '';
  in pkgs.writeScript "podman-setup" ''
    #!${pkgs.runtimeShell}

    # Dont overwrite customised configuration
    if ! test -f ~/.config/containers/policy.json; then
      install -Dm555 ${pkgs.skopeo.src}/default-policy.json ~/.config/containers/policy.json
    fi

    if ! test -f ~/.config/containers/registries.conf; then
      install -Dm555 ${registriesConf} ~/.config/containers/registries.conf
    fi
  '';

  # Provides a fake "docker" binary mapping to podman
  dockerCompat = pkgs.runCommandNoCC "docker-podman-compat" {} ''
    mkdir -p $out/bin
    ln -s ${pkgs.podman}/bin/podman $out/bin/docker
  '';

in pkgs.mkShell {

  buildInputs = [
    dockerCompat
    pkgs.podman  # Docker compat
    pkgs.runc  # Container runtime
    pkgs.conmon  # Container runtime monitor
    pkgs.skopeo  # Interact with container registry
    pkgs.slirp4netns  # User-mode networking for unprivileged namespaces
    pkgs.fuse-overlayfs  # CoW for images, much faster than default vfs
  ];

  shellHook = ''
    # Install required configuration
    ${podmanSetupScript}
  '';

}

Note that rootless podman requires newuidmap (from shadow). If you're not on NixOS, this cannot be supplied by the Nix package 'shadow' since setuid/setgid programs are not currently supported by Nix.

Containers as systemd services

{
  virtualisation.oci-containers.backend = "podman";
  virtualisation.oci-containers.containers = {
    container-name = {
      image = "container-image";
      autoStart = true;
      ports = [ "127.0.0.1:1234:1234" ];
    };
  };
}

Cross-architecture containers using binfmt/qemu

boot.binfmt = {
  emulatedSystems = [ "aarch64-linux" ];
  preferStaticEmulators = true; # required to work with podman
};

$ podman run --arch arm64 'docker.io/alpine:latest' arch
aarch64

DevContainers

Using Podman, it is possible that the process of creation of DevContainers' containers to become stuck at the "Please select an image URL" step.

To avoid this issue, you might restrict its registries configuration.

You can change the global registries with:

virtualisation.containers.registries.search = [ "docker.io" ];

For user-scoped registries you can do using Home Manager manually:

❄︎ ~/.config/home-manager/home.nix

# User-scoped `~/.config/containers/registries`
xdg.configFile."containers/registries.conf".text = ''
  [registries.search]
  registries = ['docker.io']
'';

Rootless Podman containers

Rootless Podman containers can be run using Home Manager's services.podman module

Create a user to run the rootless container:

❄︎ /etc/nixos/configuration.nix

users.groups.nginx-rootless = {
  name = "nginx-rootless";
};

users.users.nginx-rootless = {
  group = "nginx-rootless";
  linger = true; # Ensures containers keep running even when user is not logged in
  isNormalUser = true;
  extraGroups = [ "podman" ];
  shell = pkgs.bash;
};

Allow the new user to use Home Manager:

❄︎ /etc/nixos/configuration.nix

nix.settings.allowed-users = ["nginx-rootless"];

Set up Home Manager configuration for the new user, e.g. in your flakes.nix:

❄︎ /etc/nixos/flakes.nix

nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
  system = "x86_64-linux";
  modules = [
    ./configuration.nix
      home-manager.nixosModules.home-manager
      {
        home-manager.useGlobalPkgs = true;
        home-manager.useUserPackages = true;
        home-manager.users.nginx-rootless = import ./home/podman/nginx-rootless.nix;
      }
  ];
}

Set up the container using Home Manager's services.podman module. Ensure ${config.home.homeDirectory}/www exists beforehand

❄︎ /etc/nixos/home/podman/nginx-rootless.nix

{ config, pkgs, ... }:
{
  home.username = "nginx-rootless";
  home.homeDirectory = "/home/nginx-rootless";
  home.stateVersion = "25.05";

  services.podman = {
    enable = true;
    containers = {
      nginx = {
        image = "docker.io/library/nginx:latest";
        ports = [ "8080:80" ];
        volumes = [
          "${config.home.homeDirectory}/www:/usr/share/nginx/html:ro"
        ];
        autoStart = true;
      };
    };
  };
}

Limitations and quirks

• Rootless containers can't bind to ports below 1024 by default. You can allow it system-wide with boot.kernel.sysctl."net.ipv4.ip_unprivileged_port_start" = 80;, or map a high port instead (-p 8080:80)
• Rootless images and volumes are stored in ~/.local/share/containers/storage, separate from root's storage
• Files that a non-root container writes to a bind mount are owned by an unprivileged host UID (for example 100000–165535), not by you. Use :U parameter on the volume mount to ensure the mount is owned by the user and group the container runs , or --userns=keep-id to change the UID inside the container to the one of the host user