Crate podup 

podup — docker-compose → Podman translator library.

Provides parsing, variable substitution, topological ordering, and an async engine that drives container lifecycle via Podman’s native libpod REST API over a Unix socket or Windows named pipe.

Re-exports

pub use compose::collect_diagnostics;

pub use compose::parse_file;

pub use compose::parse_file_with_env_files;

pub use compose::parse_files_with_env_files;

pub use compose::parse_files_with_env_files_interp;

pub use compose::parse_str;

pub use compose::parse_str_raw;

pub use compose::resolve_levels;

pub use compose::resolve_order;

pub use compose::validate_config;

Modules

compose

Compose-file parsing, extends:/include: resolution, and topological service ordering. Compose file parsing, extends: resolution, include: merging, and topological service ordering.

env_file

env_file: loading: KEY=VALUE pairs from a service’s declared files. env_file: loading for services.

podman

Podman socket connection helpers. Podman socket connection helpers.

ports

Port-mapping parser for the docker-compose ports: format variants. Port mapping parser.

quadlet

Quadlet export: translate a parsed compose file into Podman systemd units. Translate a parsed compose file into Podman Quadlet unit files.

size

Memory and CPU value parsers shared by the engine and tests. Memory and CPU value parsers shared by the engine and tests.

substitute

Docker Compose ${VAR}/$VAR substitution over raw YAML before parsing. Docker Compose variable substitution.

ui

Terminal colour/styling, honouring --ansi, NO_COLOR, and TTY detection. Terminal styling — the single place that decides whether to colour output and holds the palette, so colour stays consistent and always honours --ansi, NO_COLOR, and whether the target stream is a TTY.

update

Secure self-update for the podup binary (signature-verified release fetch). Secure self-update for the podup binary.

Structs

BuildOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. docker compose build-style CLI overrides. Each augments (never weakens) the per-service build: config: a flag forces the behaviour on even when the compose file leaves it off.

Client

The libpod Client, surfaced for callers that talk to Podman directly. Podman libpod REST API client.

CommitOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Options for Engine::commit_with_options, mirroring docker compose commit (-m/--message, -a/--author, -p/--pause, -c/--change). Kept off the frozen commit signature so the 1.0 library API stays stable.

CpOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Options for Engine::cp_with_options, mirroring docker compose cp flags.

Engine

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Handle through which all Podman operations for a project are dispatched.

EventsOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Options for Engine::stream_events, mirroring docker compose events (--since, --until, --filter).

ExecOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Options for Engine::exec, mirroring docker compose exec flags.

ImagesOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Options for Engine::images_with_options.

LogsDisplay

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Prefix-display options for Engine::logs_with_display (docker compose logs --no-color / --no-log-prefix). Kept off the frozen LogsOptions struct so the 1.0 library API stays stable.

LogsOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Options for Engine::logs_with_options, mirroring docker compose logs.

LsOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Options for list_projects (docker compose ls).

ProjectLock

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Guard holding a held project lock. Dropping it releases the lock (the OS drops the flock when the underlying file descriptor is closed).

PsFilterOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Service/status/name filters for Engine::ps_filtered (docker compose ps --services, [SERVICE...], --status, --filter). Kept off the frozen PsOptions struct so the 1.0 library API stays stable.

PsOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Options for Engine::ps_with_options, mirroring docker compose ps.

PullOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Options for Engine::pull_services_with_options, mirroring docker compose pull flags. The --policy override is carried on the engine (see Engine::with_up_overrides), not here.

PushOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Options for Engine::push, mirroring docker compose push (plus a Podman --tls-verify escape hatch for insecure/local registries).

RunOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Options for Engine::run.

RunOverrides

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Extra docker compose run flag overrides threaded through the engine builder (Engine::with_run_overrides). These are CLI-only refinements of a run invocation; they live here rather than on the frozen RunOptions public struct so the 1.0 library API stays stable, mirroring how the up image-acquisition overrides are carried on the engine.

StatsOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Options for Engine::stats_with_options, mirroring docker compose stats and the table-shaping flags the other list commands expose. Kept off the frozen Engine::stats signature so the 1.0 library API stays stable.

VolumesOptions

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Options for Engine::list_volumes, mirroring docker compose volumes.

Enums

ComposeError

The crate’s error type and Result alias, surfaced so callers handle one error enum across parsing and engine calls. All errors produced by podup.

Functions

is_safe_project_name

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Whether name is safe to use as a single path component and container name prefix. Matches docker-compose’s project-name rule ^[a-z0-9][a-z0-9_-]*$: non-empty, bounded, lowercase ASCII letters/digits/-/_ only, and a first character that is a letter or digit. This rejects a leading separator (-rf, --all, _x — a latent flag-injection vector for forwarding paths), uppercase, dots (., .., hidden directories, bad. trailing-dot names), and all-separator names.

list_projects

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. List podup projects on the host (docker compose ls). Groups every podup.project-labelled container by project; by default shows only projects with at least one running container (all includes stopped ones). For the --filter name=/status= predicates use list_projects_filtered.

list_projects_filtered

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. List podup projects (docker compose ls) narrowed by --filter predicates (name=<NAME>, status=<running|exited>). The filters slice is kept off the frozen LsOptions struct so the 1.0 library API stays stable.

resolve_image_digests

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Return a copy of file with every service image: rewritten to its registry digest (repo@sha256:...), matching docker compose config --resolve-image-digests. An image with no registry digest in local storage (e.g. built locally, or never pulled) is left unchanged with a warning.

retain_active_profiles

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Remove services excluded by the active profile set, in place.

retain_active_profiles_with_targets

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Like retain_active_profiles, but also keeps any service named in targets even when its profile is inactive: naming a service on the command line activates its profile (docker compose), so per-service subcommands (start, stop, build, push, pull, …) can still address it.

validate_stop_timeout

The lifecycle Engine and its per-command option/override types, plus the project-name/listing helpers — the surface a CLI drives compose operations through. Validate a CLI -t/--timeout value at the trust boundary.

Type Aliases

Result

The crate’s error type and Result alias, surfaced so callers handle one error enum across parsing and engine calls. Convenience alias for std::result::Result<T, ComposeError>.