• 👍 Part of NixOS, no additional dependencies.
• 👍 Rootless container support without additional dependencies.
• 👍 Supports Docker.
• 😐 Compatible with podman auto-update (requires external setup).
• 👎 Limited options.
• 👎 Lack of support for networks, pods, etc.

• 👍 Supports Docker.
• 😐 More indirection and moving parts.
• 👎 Limited options.
• 👎 Incompatible with podman auto-update.

• 👍 Even less indirection.
• 😐 Compatible with podman auto-update (requires external setup).
• 😐 Requires more work to set up.
• 👎 Not integrated with rest of Nix configuration.

• 👍 Part of Home Manager, no additional dependencies if you are already using it.
• 👎 Lack of rootful container support.

• 👍 Supports Docker.
• 😐 Compatible with podman auto-update (requires external setup).
• 😐 More indirection and moving parts.
• 👎 Less maintainable Nix files due to generated boilerplate.
• 👎 Manual regeneration is required.
• 👎 Lack of rootless container support.
• 👎 Limited options.
• 👎 Fragmented configuration with source of truth being outside of Nix.

flake.nix

{
    inputs = {
        nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
        quadlet-nix.url = "github:SEIAROTg/quadlet-nix";
    };
    outputs = { nixpkgs, quadlet-nix, ... }@attrs: {
        nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
            system = "x86_64-linux";
            modules = [
                ./configuration.nix
                quadlet-nix.nixosModules.quadlet
            ];
        };
    };
}

configuration.nix

{ config, ... }: {
    # ...
    virtualisation.quadlet = let
        inherit (config.virtualisation.quadlet) networks pods;
    in {
        containers = {
            nginx.containerConfig.image = "docker.io/library/nginx:latest";
            nginx.containerConfig.networks = [ "podman" networks.internal.ref ];
            nginx.containerConfig.pod = pods.foo.ref;
            nginx.serviceConfig.TimeoutStartSec = "60";
        };
        networks = {
            internal.networkConfig.subnets = [ "10.0.123.1/24" ];
        };
        pods = {
            foo = { };
        };
    };
}

flake.nix

{
    inputs = {
        nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
        home-manager.url = "github:nix-community/home-manager";
        home-manager.inputs.nixpkgs.follows = "nixpkgs";
        quadlet-nix.url = "github:SEIAROTg/quadlet-nix";
    };
    outputs = { nixpkgs, quadlet-nix, home-manager, ... }@attrs: {
        nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
            system = "x86_64-linux";
            modules = [
                ./configuration.nix
                home-manager.nixosModules.home-manager
                # to enable podman & podman systemd generator
                quadlet-nix.nixosModules.quadlet
            ];
        };
    };
}

configuration.nix

{
    # ...
    users.users.alice = {
        # ...
        # required for auto start before user login
        linger = true;
        # required for rootless container with multiple users
        autoSubUidGidRange = true;
    };
    home-manager.users.alice = { pkgs, config, ... }: {
        # ...
        imports = [ inputs.quadlet-nix.homeManagerModules.quadlet ];
        # This is crucial to ensure the systemd services are (re)started on config change
        systemd.user.startServices = "sd-switch";
        virtualisation.quadlet.containers = {
            echo-server = {
                autoStart = true;
                serviceConfig = {
                    RestartSec = "10";
                    Restart = "always";
                };
                containerConfig = {
                    image = "docker.io/mendhak/http-https-echo:31";
                    publishPorts = [ "127.0.0.1:8080:8080" ];
                    userns = "keep-id";
                };
            };
        };
    };
}

If you wish to write raw Quadlet files instead of using the Nix options, you may do so with rawConfig. Using this will cause all other options (except autoStart) to be ignored though.

{ config, ... }: {
    # ...
    virtualisation.quadlet = let
        inherit (config.virtualisation.quadlet) networks pods;
    in {
        containers = {
            nginx.rawConfig = ''
                [Container]
                Image=docker.io/library/nginx:latest
                Network=podman
                Network=${networks.internal.ref}
                Pod=${pods.foo.ref}
                [Service]
                TimeoutStartSec=60
            '';
        };
        networks = {
            internal.networkConfig.subnets = [ "10.0.123.1/24" ];
        };
        pods = {
            foo = { };
        };
    };
}

Podman natively supports multiple transport, including docker-archive that can be used with pkgs.dockerTools.

{ pkgs, ... }: let
    image = pkgs.dockerTools.buildImage {
        # ...
    };
in {
    virtualisation.quadlet.containers = {
        foo.containerConfig.image = "docker-archive:${image}";
    };
}

See: https://docs.podman.io/en/v5.5.0/markdown/podman-run.1.html#image

quadlet-nix tries to put containers into full management under systemd. This means once a container crashes, it will be fully deleted and debugging mechanisms like podman ps -a or podman logs will not work.

However, status and logs are still accessible through systemd, namely, systemctl status <service name> and journalctl -u <service name>, where <service name> is container name, <network name>-network, <pod name>-pod, or similar. These names are the names as appeared in virtualisation.quadlet.containers.<container name>, rather than podman container name, in case it's different.

Check if that option is supported by Podman Quadlet here: https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html.

If it exists, please create an issue or send a PR to add.

Otherwise, please use PodmanArgs and GlobalArgs to insert additional command line arguments as quadlet-nix does not intend to support options beyond what Quadlet offers.