podup

podup runs your docker-compose.yml on rootless Podman — a single static binary, written in Rust, with no daemon and no Python runtime.

flowchart LR
	A["docker-compose.yml"] --> B["podup"]
	B -->|"parse · substitute · order"| C["Podman REST API"]
	C --> D["containers"]
	C --> E["networks"]
	C --> F["volumes"]

✨ Features

• 🚀 Drop-in workflow — up, down, start, stop, ps, logs, exec, run, cp, build, pull, restart, rm, kill, pause, unpause, top, port, images, volumes, events, config …and more — see the command reference
• 🔒 Rootless by design — drives rootless Podman over its native libpod REST API
• 📄 Compose-spec parsing — YAML anchors, extends, include, profiles, env_file, variable substitution with modifiers
• 🔁 Dependency-aware — depends_on ordering with service_started, service_healthy, and service_completed_successfully conditions
• 🔢 Replicas — scale:/deploy.replicas, the scale command, and up --scale SERVICE=N, with named replica containers
• 🔐 Secrets & configs — inline content, file, environment, and external: true Podman-native secret sources, staged securely
• 👀 Watch mode — sync, rebuild or restart services on file changes per develop.watch rules
• ⚙️ Systemd Quadlet export — generate quadlet emits native podman-systemd.unit files to run your stack under systemd, no daemon
• ⌨️ Shell completions — completions <shell> for bash, zsh, fish and more (the Debian package installs them)
• 📦 Single binary — statically musl-linked on Linux, no runtime dependencies
• 🦀 Library too — embed the parser and engine in your own Rust project

✅ Requirements

• Podman ≥ 5.0 — podup talks to Podman's native libpod REST API (the /v5.0.0/libpod surface) and assumes a Podman 5.x engine. Rootless is the default and recommended posture.
• Supported platforms:
  • Linux (x86_64, arm64) — talks to the rootless Podman socket directly.
  • macOS (x86_64, arm64) — via podman machine (applehv or vz backend); podup uses the host-side unix:// socket.
  • Windows (x86_64, arm64) — via podman machine; podup uses the host-side npipe:// named pipe.

The socket must be local: only unix:// (and npipe:// on Windows) are accepted — remote tcp:///ssh:// endpoints are rejected.

📥 Install

Linux and macOS:

curl -fsSL https://glyndor.net/podup/install/unix | bash

Windows (PowerShell):

irm https://glyndor.net/podup/install/windows | iex

Binaries for Linux and macOS (x86_64 and arm64) plus Windows (x86_64 and arm64), SHA-256 verified, with build provenance attestations. On macOS and Windows, podup talks to the podman machine VM through its host-side socket or named pipe. Both installers verify the Ed25519 signature over SHA256SUMS (or the GitHub build-provenance attestation) and fail closed otherwise. Or build from source:

cargo build --release

Debian / Ubuntu (apt)

On Debian and Ubuntu (amd64 and arm64), install from the Glyndor apt repository so updates arrive through apt upgrade:

curl -fsSL https://glyndor.net/podup/install/unix | bash -s -- --apt

This installs the glyndor-archive-keyring package (registering the signed repository at https://apt.glyndor.net) and then podup. Because the signing key ships as a package, key renewals are picked up automatically by apt upgrade; the apt build omits self-update, since apt owns upgrades. To set it up by hand:

curl -fsSLO https://apt.glyndor.net/glyndor-archive-keyring.deb
sudo dpkg -i glyndor-archive-keyring.deb
sudo apt update && sudo apt install podup

Updating

podup update            # download and install the latest signed release
podup update --check    # report whether a newer release exists, install nothing

podup update replaces the running binary in place, but only after verifying the release's Ed25519 signature against the public key embedded in your build and matching its SHA-256 checksum. It fails closed: a bad signature, missing key, or checksum mismatch aborts before the installed binary is touched. See docs/self-update.md for the trust model. Installing into a system directory (e.g. /usr/local/bin) needs elevation — re-run with sudo.

🚀 Quick start

podup up --detach                      # docker-compose.yml in the current directory
podup -f stack.yml -p myapp up -d      # explicit file and project name
podup ps                               # list project containers
podup logs api --follow                # follow one service's logs
podup down --volumes                   # tear down, removing named volumes
podup generate quadlet -o ~/.config/containers/systemd  # emit systemd Quadlet units

⚖️ vs. alternatives

📊 Benchmarks

podup and podman-compose both drive the same Podman, so this is a pure tool comparison — identical engine, identical digest-pinned and pre-pulled images, identical compose file per scenario, the same op flags for both. Each number is the median over 10 measured iterations (2 warm-up runs discarded).

Wall-clock (seconds, lower is better)

Memory + CPU per command (peak RSS / CPU time, median)

This is the client-side cost of running the tool. podup is a static binary that hands the work to the long-running Podman service, so its own CPU is near zero and its memory is flat; podman-compose is Python that shells out to podman on every call and is charged for the work it waits on. (The engine does the container work either way — this measures what invoking the tool costs.)

Across every op podup stays around 7 MiB of peak memory and near-zero client CPU; podman-compose ranges 59–89 MiB and 0.15–3.3 s of CPU.

Host: AMD Ryzen 7 5700X (16 threads), Linux 6.17 x86_64, CPU governor performance, Podman 5.4.2, podman-compose 1.3.0; the tool process pinned with taskset. Measured 2026-06-23. On multi-healthcheck the high p95/stdev on podup's up is the service_healthy gate — it waits on the dependency's healthcheck interval, so the tail varies; the median still leads.

docker-compose is not in these tables. It drives dockerd, a different daemon, so including it would be an end-to-end stack comparison, not a pure-tool one — and this host had no Docker Engine, so it is left out rather than estimated.

podup is faster and lighter on every operation measured here, widest on the volume- and service-heavy stacks. The harness, scenarios, and full methodology live in bench/; reproduce with bench/run.sh. Every scenario is published, whoever wins.

🦀 Library usage

use podup::{parse_file, podman, Engine};

#[tokio::main]
async fn main() -> podup::Result<()> {
	let file = parse_file(std::path::Path::new("docker-compose.yml"))?;
	let client = podman::connect(None)?;
	let engine = Engine::new(client, "myproject".to_string());
	engine.up(&file).await?;
	Ok(())
}

[dependencies]
podup = "1"

🔒 Stability & versioning

podup follows Semantic Versioning. From 1.0.0 onward:

• The CLI surface (subcommands, flags, exit codes) and the library surface re-exported from the crate root (parse_file, collect_diagnostics, Engine, ComposeError, …) are covered by the stability guarantee. Breaking changes bump the major version and are called out in the release notes.
• Public enums and the compose/quadlet result structs are #[non_exhaustive], so new variants and fields can be added in a minor release without breaking downstream code — always include a wildcard arm and avoid exhaustive struct construction.
• The libpod wire types are an internal implementation detail (not re-exported) and may change in any release.
• MSRV: Rust 1.85. A bump to the minimum supported Rust version is a minor-version change, never a patch.

📖 Docs

• Command reference — every subcommand, its options, and what it does
• Migrating from Docker Compose — compatibility guide, rootless differences, deprecated fields
• Self-update — the podup update trust model and verification flow
• Security model — privilege posture, trust boundaries, SBOM and air-gap notes
• Debian packaging — building and distributing a .deb

Contributing & security

See the org-wide contributing guide. Report vulnerabilities privately via the Security tab — never in a public issue.

License

Apache-2.0