How to use the QIIME 2 workshop container

Using a QIIME 2 workshop container will enable you (or your students) to use QIIME 2 on the command line or through Jupyter Lab in a containerized environment that should be consistent across different host operating systems (i.e., whether you’re running on macOS, Linux, or Windows).

We recommend using either Podman or Docker. Before you jump in with QIIME 2, follow the “Get Started” (i.e., install) instructions for one or the other on the project’s website, and confirm that it’s working according to the Podman’s or Docker’s instructions. (We don’t link to their instructions here so that we don’t send you to an outdated link.)

Pull the container image¶

After installing Docker or Podman, we next need to pull (i.e., download) the image that contains our QIIME 2 environment. Copy/paste the relevant commands.

Docker instructions

Podman instructions

First, open Docker Desktop.

Then, in a command terminal, run:

docker \
 image \
 pull quay.io/qiime2/<distribution>-workshop:<epoch>

The first time you start podman, you’ll need to run the following command:

podman machine init

Then, each time you restart your computer, you’ll need to run:

podman machine start

Then, run:

podman \
 image \
 pull quay.io/qiime2/<distribution>-workshop:<epoch>

The above commands will require modification to replace <distribution> with the QIIME 2 distribution that you’d like to install, and to replace <epoch> with the QIIME 2 epoch that you’d like to install. For example, if you’d like to install the metagenome distribution from the 2024.10 epoch, your quay.io URL would look like:

quay.io/qiime2/metagenome-workshop:2024.10

You can browse our container collection on quay.io at https://quay.io/organization/qiime2.

Create a data storage volume¶

Next, we create a volume that will be used to store any data we generate during our analysis. Data that you create in your container will persist and be available the next time you start the container.

Docker

Podman

docker volume create qiime2-workshop

Start the container¶

Next, we’ll start the container.

Docker

Docker on Apple M-series

Podman

Podman on Apple M-series

docker container run \
  -itd \
  --rm \
  -v qiime2-workshop:/home/qiime2 \
  --name qiime2-workshop \
  -p 8889:8888 \
  quay.io/qiime2/<distribution>-workshop:<epoch>

Again, you’ll need to update <distribution> and <epoch> as described above.

Interact with Jupyter Lab and QIIME 2¶

Once the container is running, you can interact with it by opening the following link: http://localhost:8889 This will open a Jupyter Lab window in your web browser.

Using QIIME 2 through the command line¶

In the Jupyter Lab window, click the Terminal button toward the bottom right. (Look for a block box with a $ symbol in it.)

You’ll then have command line access to QIIME 2.

In the terminal environment, run the following command:

qiime info

This provides information on your QIIME 2 environment, including the versions of the QIIME 2 framework, Python, and the installed plugins.

To get a start getting a feel for what you can do with your QIIME 2 deployment, run:

qiime --help

This provides a list of the available QIIME 2 plugins. To learn more about what you can do with one of them (for example, the feature-table plugin), call:

qiime feature-table --help

This will display a list of actions (i.e., commands) that are available in that plugin. To learn how to use one, for example filter-samples, call:

qiime feature-table filter-samples --help

That will provide help text and a list of examples that illustrate how to use the command to achieve different goals.

You can return to this document when you need to start, stop, or update your container.

Stopping the container¶

When you’re no longer using the container, you can stop it as follows:

Docker

Podman

docker container stop qiime2-workshop

If using Docker, once you’re done using your container and don’t have any other containers running, it’s a good idea to quit Docker so it’s not using resources unnecessarily.

Building the image locally (optional; experts only ♦♦)¶

Expert users may ultimately be interested in modifying the image used here. This can be done with docker as follows. Pulling the image will be quicker and easier.

First, download the Dockerfile for the workshop container.

wget https://raw.githubusercontent.com/qiime2/distributions/refs/heads/dev/Dockerfile.workshop

Then, edit the file to specify the epoch (e.g., 2024.10) and distribution (e.g., amplicon) that you want to build your container for.

Next, make sure that the Docker daemon is running (e.g. by launching Docker Desktop).

Finally, build the image.

Standard Instructions

M-series Mac Instructions

docker image build -t my-image-name .