05. Managing Containers with Docker on Portenta X8

This tutorial shows how to install and manage your containers using Docker.


Docker is a platform full of applications called containers. Containers are isolated solutions; thus, they do not have to depend on your environment, making them portable and consistent throughout development, testing, and production.

You can download, install, use, and share applications in the form of containers. You can find all the available container images on the hub.docker.com page.

In this tutorial, we will go through the steps of how to install, run, and remove Docker's official Hello-World image.


  • Learn how to list installed and active containers
  • Learn how to install a container
  • Learn how to run a container manually
  • Learn how to uninstall a container

Hardware and Software Requirements

Make sure to have the Portenta X8 with the latest image as well as the bootloader. Please check how to flash your Portenta X8 to have the latest version.

Using Docker

The Portenta X8 provides Docker CLI by default. To verify its correct installation, use the following command:

1docker -v

Or as well:

1docker --version

To use this tool, you will need to connect to your device first. Check how to connect using adb/ssh.

You can explore Docker's comprehensive reference documentation, covering all tool features in depth, at docs.docker.com.

The following steps will show how to pull the "Hello World" image from Docker Hub, run the container, and view its status.

To avoid a lack of permissions while launching

adb shell
, you may type the following:
newgrp - docker

The previous command and other important info about Linux on your Portenta are described in the Portenta X8 User Manual.

How to Install a Container

First, you will need to search for "Hello World" container image. The container image can be found within the Docker hub, where you will be able to find a variety of readily-available container images. It will be used to verify docker is working as intended with the Portenta X8.

The following command is used to pull the

image. The Docker hub page for images has the instructions to pull the image and deploy the container.

1docker pull hello-world

Docker CLI pulling a container
Docker CLI pulling a container

Run The Installed Container

Use this command to begin a container from the


1docker run hello-world

Docker CLI running Hello World app
Docker CLI running Hello World app

To see a list of active and exited containers,

docker ps -a
should be used after running a container at least once with
docker run

Listing Active Containers And Available Docker Images

The following command will display the active containers and will show the

container if it was able to run successfully. The
message will let you know if the container is active or has finished operation depending on its purpose.

1docker ps -a

Docker CLI listing all the active containers
Docker CLI listing all the active containers

The list of available images, including installed

image, can be verified using the following command:

1docker images

Docker CLI images
Docker CLI images

How to Remove A Container

You will need to obtain an assigned

to remove a container of your choice. This can be found by listing all containers, including inactive ones:

1docker ps -a

The remove (

) command is then used with the desired container identifier to proceed with the removal process.

1docker container rm <CONTAINER ID>

For this example, the command

docker ps -a
will show the
of the
container designated as:

If you encounter an error stating that the container cannot be removed, it may mean that the container has an ongoing operation that can be checked with a


If this is the case, you will need to stop the container and verify with a

message that it has exited successfully. To do this, the following command is used:

1docker stop <CONTAINER ID>

Every time the image is re-installed or re-ran, the

will be different than the previous identifier

Docker CLI container uninstall
Docker CLI container uninstall

Using the

docker ps -a
after container removal, the
container should no longer be present as an active container.

The same goes for the images if you would like to free some space. The removal command will now be as follows using

found within the image table:

1docker rmi <IMAGE ID>

If you run

docker images
again, you will see that the
image is not showing up anymore.


In this tutorial, you have learned how to use Docker with Portenta X8. You have learned to download an image, manage, and deploy the container, and ultimately run on Portenta X8. You have also learned to remove the image and the container to control Portenta X8's available resources.

Next Steps

  • Now that you have the base of the workflow to use Docker, go to its docs page and make sure you understand all the features.
  • Look for a container image from Docker hub, install it and make your own application out of it.
  • Create a container to run your custom-made application. For this, it may interest you Deploy a Custom Container with Portenta X8 Manager tutorial.

Suggest changes

The content on docs.arduino.cc is facilitated through a public GitHub repository. If you see anything wrong, you can edit this page here.


The Arduino documentation is licensed under the Creative Commons Attribution-Share Alike 4.0 license.