Skip to main content

Podman

Creating and Destroying Containers Using Podman

New to Podman? Here's a basic tutorial on creating, listing, stopping and destroying containers with Podman.

In this part of the Podman series, let's see about creating and deleting containers.

In case you didn't know already, Podman is a Docker alternative for managing containers. It follows a similar command structure as Docker.

Pulling images beforehand

Each container needs an image to exist. Without an image, nothing gets executed. Hence, an image needs to be "pulled" from an image registry.

Some of the popular image registries are:

The syntax for pulling an image using Podman is as follows:

podman pull [OPTIONS] FULLY_QUALIFIED_IMAGE_NAME[:tag|@digest]

If you are wondering what FULLY_QUALIFIED_IMAGE_NAME means, look at the two commands below:

# with FQIN
podman pull docker.io/library/debian

# without FQIN
podman pull debian

As you might have noticed, in a fully qualified image name, the format is as such: registry/username/image-name. The registry address for hub.docker.com is docker.io.

To pull a specific tag, apply the tag after the image name, followed by a colon (:). Following is the command to pull the stable-slim tag of the Debian image:

podman pull docker.io/library/debian:stable-slim

List available images

Once one or more images are pulled, you can check which images are available locally with the podman images command. Since I pulled the debian:stable-slim image, my output looks like the following:

$ podman images
REPOSITORY                TAG          IMAGE ID      CREATED     SIZE
docker.io/library/debian  stable-slim  86f9b934c377  2 days ago  77.8 MB

Now that you have your image, you can create a new container.

Creating a container

To create a container with Podman, use the podman run command in this fashion:

podman run [OPTIONS] image [COMMAND [ARGS]]

I will use the -d option to keep the container running in the background. I will also use the -t option to allocate a pseudo-TTY to the Debian image, so it keeps running. You can find a complete list of available options here.

For now, I will create a simple container based on the Debian stable-slim image that you pulled earlier.

podman run -d -t debian:stable-slim

If the container creation were successful, you would receive a random string of alphanumeric characters as the command output. This is the unique container ID.

61d1b10b5818f397c6fd8f1fc542a83810d21f81825bbfb9603b7d99f6322845

List containers

To see all the containers that are running, use the podman ps command. This is similar to the ps command in Linux. Instead of showing system processes, it shows the running containers and their details.

Since I used the -t option as a hack to keep the Debian container running, let us see what the output of the podman ps command looks like.

$ podman ps
CONTAINER ID  IMAGE                                 COMMAND     CREATED         STATUS             PORTS       NAMES
61d1b10b5818  docker.io/library/debian:stable-slim  bash        44 seconds ago  Up 44 seconds ago              gallant_mahavira

From here, you can get various details about our container name. Some of the details are the shorter length but unique container ID, the image used to create this container, when it was created, what ports of the host machine are mapped to which ports of the container and the container name.

Here, you can see that the image used was debian:stable-slim, it was created 44 seconds ago and the container name is gallant_mahavira. When a container name is not specified, a name is generated at random. You can pass the container name when creating a container using the --name CONTAINER_NAME option.

A container can either be running or it can not be running (stopped). The stopped containers can be listed like this:

podman container list -a

I don't have any stopped containers yet so let's learn to stop them first.

Stopping containers

To stop a container, use the podman stop command with either the container ID or the container name.

Below is the syntax of the podman stop command:

podman stop [CONTAINER_NAME|CONTAINER_ID]

Let me stop the running container using its name:

$ podman stop gallant_mahavira
gallant_mahavira

Now you can use the aforementioned command to list all the containers, including the stopped ones:

$ podman container list -a
CONTAINER ID  IMAGE                                 COMMAND     CREATED         STATUS                      PORTS       NAMES
61d1b10b5818  docker.io/library/debian:stable-slim  bash        14 minutes ago  Exited (137) 3 minutes ago              gallant_mahavira
💡
The commands podman ps, podman container ps, podman container list and podman container ls all link to the same binary and these commands can be used interchangeably. i.e., you can run the podman ps -a command instead of the podman container list -a command and get the same output.

Starting a container that was stopped

To start a container that was either stopped or failed, use the podman start command.

Assuming, the container you created from the Debian image failed, for whatever reason, you can start it again using its container name or ID, like so:

$ podman start 61d1b10b5818f397c6fd8f1fc542a83810d21f81825bbfb9603b7d99f6322845

Destroying a container

To completely delete or destroy a container, you use the podman rm command.

🚧
Please ensure to stop the container before deleting it.

Once a container is deleted, it will no longer exist. So, when you check the output of the podman container list -a command, the container will not exist in the list.

Here's an example of stopping and deleting a container with Podman. I used both the container name and ID in the example.

$ podman ps
CONTAINER ID  IMAGE                                 COMMAND     CREATED         STATUS           PORTS       NAMES
61d1b10b5818  docker.io/library/debian:stable-slim  bash        44 minutes ago  Up 1 second ago              gallant_mahavira

$ podman stop gallant_mahavira
gallant_mahavira

$ podman rm 61d1b10b5818
61d1b10b5818f397c6fd8f1fc542a83810d21f81825bbfb9603b7d99f6322845

$ podman container list -a
CONTAINER ID  IMAGE       COMMAND     CREATED     STATUS      PORTS       NAMES

As you can see now, the container is completely gone. If you want, you can create a new container using any image you want.

Conclusion

The tutorial covers the basics of container management with Podman. You learned about creating containers, listing them, stopping them and deleting them.

If you have any doubts, please do not hesitate to comment!