podman-run

Run command in a new container from a tagged image

$ podman run [image:tag] [command]

$ podman run --detach [image:tag] [command]

$ podman run --rm --interactive --tty [image:tag] [command]

$ podman run --env '[variable]=[value]' --env [variable] [image:tag] [command]

$ podman run --volume /[path/to/host_path]:/[path/to/container_path] [image:tag] [command]

$ podman run --publish [host_port]:[container_port] [image:tag] [command]

$ podman run --entrypoint [command] [image:tag]

$ podman run --network [network] [image:tag]

podman run [options] image [command] [arg...]

-d, --detach
    Runs the container in the background, printing the new container ID.

--name=name
    Assigns a specific name to the container instead of a randomly generated one.

-p, --publish=port
    Maps a container port to a host port (e.g., 8080:80).

-v, --volume=source:destination[:options]
    Mounts a host path or named volume into the container.

-e, --env=key=value
    Sets environment variables inside the container.

--rm
    Automatically removes the container filesystem upon exit.

--network=mode|name|id
    Connects the container to a specified network.

--mount=type=bind,source=...,destination=...
    Attaches a filesystem mount to the container (more explicit than --volume).

--restart=policy
    Defines the container's restart policy (e.g., 'no', 'on-failure', 'always').

--user=name|uid[:group|gid]
    Specifies the user and/or group to run the command as inside the container.

--security-opt=option
    Configures container security options (e.g., 'no-new-privileges').

--hostname=name
    Sets the container's hostname.

--entrypoint=command
    Overrides the default ENTRYPOINT command of the image.

-i, --interactive
    Keeps STDIN open even if not attached, allowing for interactive input.

-t, --tty
    Allocates a pseudo-TTY for the container, often used with -i.

--read-only
    Mounts the container's root filesystem as read-only.

--pull=always|missing|never
    Controls when the image is pulled from the registry (default is 'missing').

--label=key=value
    Adds metadata labels to the container.

--add-host=host:ip
    Adds custom host-to-IP mappings in the container's /etc/hosts file.

--device=host_path[:container_path][:permissions]
    Adds a host device to the container.

--cap-add=capability
    Adds Linux capabilities to the container.

--cap-drop=capability
    Drops Linux capabilities from the container.

The podman-run command is a fundamental tool for managing OCI (Open Container Initiative) containers with Podman, a daemonless container engine. It's used to launch a new container from a specified image, executing a command within that isolated environment. Unlike traditional daemon-based container engines, Podman operates directly with the container runtime, making it well-suited for rootless operations and integration with systemd. podman-run allows users to configure various aspects of the container's lifecycle and environment, including port mappings, volume mounts, environment variables, network configurations, and resource limits. It enables the creation of ephemeral or persistent containers, facilitating application deployment, development, and testing workflows in a secure and flexible manner, often serving as a drop-in replacement for docker run.

When running podman-run as a non-root user (rootless containers), certain operations like binding to privileged ports (below 1024) or mounting specific host paths may require additional configurations or might be restricted. While podman-run automatically pulls images if not present locally, network connectivity is required for this action. Unlike Docker, Podman is daemonless, meaning containers are managed directly by the user's process and don't rely on a central daemon, which can impact persistent service management (often handled via systemd for long-running containers).

By default, if the specified image is not found locally, podman-run will automatically attempt to pull it from configured container registries (e.g., Docker Hub, Quay.io). This behavior can be explicitly controlled using the --pull option, allowing users to force a pull, prevent pulls, or only pull if the image is missing locally.

A container created with podman-run executes the specified command. Once the command finishes, the container will stop. Unless the --rm flag is used, the stopped container and its writable layer will persist on the system, consuming disk space. Users can later restart, inspect, or remove these stopped containers using other podman commands.

A significant feature of Podman is its support for rootless containers. When podman-run is executed by a regular (non-root) user, it creates a container that runs without root privileges on the host system. This enhances security by isolating the containerized process, preventing it from having root access to the host's kernel or system files, and leveraging user namespaces for privilege separation.

Podman emerged as a daemonless alternative to Docker, primarily developed by Red Hat. Its design philosophy emphasizes security, particularly rootless operations, and integration with standard Linux tools like systemd. The podman-run command was conceived to mimic the behavior and options of docker run, making it easy for users to transition between the two container engines. Its development has focused on OCI compliance, ensuring interoperability with other container tools and registries, and promoting a more modular approach to container management compared to monolithic daemon architectures.

podman(1), podman-build(1), podman-start(1), podman-stop(1), podman-ps(1), podman-images(1), podman-network(1), docker-run(1)