---
name: Registry-getting-started
title: Getting started with Container Registry
description: IBM Cloud® Container Registry provides a multi-tenant private image registry that you can use to store and share your container images with users in your IBM Cloud account.
last-updated: 2025-08-12
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/Registry?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Getting started with Container Registry
{: #getting-started}
{: toc-content-type="tutorial"}
{: toc-services="containers"}
{: toc-completion-time="45m"}

IBM Cloud® Container Registry provides a multi-tenant private image [registry](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_overview&format=markdown#overview_elements_registry) that you can use to store and share your [container images](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_overview&format=markdown#overview_elements_container_image) with users in your IBM Cloud account.
{: shortdesc}

The IBM Cloud console includes a brief Quick Start. To find out more about how to use the IBM Cloud console, see [Managing image security with Vulnerability Advisor](https://cloud.ibm.com/docs/Registry?topic=Registry-va_index&interface=ui&format=markdown).

Do not put personal information in your container images, namespace names, description fields, or in any image configuration data (for example, image names or image labels).
{: important}

## Before you begin
{: #gs_registry_prereqs}

Install the IBM Cloud command-line interface (CLI) so that you can run the IBM Cloud `ibmcloud` commands, see [Getting started with the IBM Cloud CLI](https://cloud.ibm.com/docs/cli?topic=cli-getting-started&format=markdown).

The following instructions assume that you’re in your own account with permission to do everything. If you find that you can't run the commands and you’re a member of an account that is owned and administered by someone else, you might lack the correct permissions to configure and operate the Container Registry service. In which case, you must ask your administrator to give you the required IAM service access role permissions. For more information, see [Why can't I get started with Container Registry?](https://cloud.ibm.com/docs/Registry?topic=Registry-troubleshoot-get-started&format=markdown)
{: note}

## Install the Container Registry CLI
{: #gs_registry_cli_install}
{: step}

1. Install the `container-registry` CLI plug-in by running the following command:

    ```txt
    ibmcloud plugin install container-registry
    ```
    {: pre}

    For more information about installing plug-ins, see [Extending IBM Cloud CLI with plug-ins](https://cloud.ibm.com/docs/cli?topic=cli-plug-ins&format=markdown).

## Set up a namespace
{: #gs_registry_namespace_add}
{: step}
{: help}
{: support}

Create a [namespace](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_overview&format=markdown#overview_elements_namespace). The namespace is created in the [resource group](https://cloud.ibm.com/docs/account?topic=account-rgs&format=markdown) that you specify so that you can configure access to resources within the namespace at the resource group level. If you don't specify a resource group, and you don't target a resource group, the default resource group is used. Namespaces that are assigned to a resource group show in the **Resource list** page of the IBM Cloud console.

1. Log in to IBM Cloud.

    ```txt
    ibmcloud login
    ```
    {: pre}

    If you have a federated ID, use `ibmcloud login --sso` to log in. Enter your username and use the provided URL in your CLI output to retrieve your one-time passcode. If you have a federated ID, the login fails without the `--sso` and succeeds with the `--sso` option.
    {: requirement}

    You don't need to log in to Container Registry until you want to push an image, see [Step 5: Push images to your namespace](https://cloud.ibm.com/docs/Registry?topic=Registry-getting-started&format=markdown#gs_registry_images_pushing).
    {: note}

2. Add a namespace to create your own image [repository](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_overview&format=markdown#overview_elements_repository). Replace `MY_NAMESPACE` with your preferred namespace.

    The namespace must be unique across all IBM Cloud accounts in the same region. Namespaces must have 4 - 30 characters, and contain lowercase letters, numbers, hyphens (-), and underscores (_) only. Namespaces must start and end with a letter or number.
    {: requirement}

    ```txt
    ibmcloud cr namespace-add MY_NAMESPACE
    ```
    {: pre}

    You can put the namespace in a resource group of your choice by using one of the following options.

    - Before you create the namespace, run the [`ibmcloud target -g RESOURCE_GROUP`](https://cloud.ibm.com/docs/cli?topic=cli-ibmcloud_cli&format=markdown#ibmcloud_target) command, where `RESOURCE_GROUP` is the resource group.
    - Specify the resource group by using the `-g` option on the [`ibmcloud cr namespace-add`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_namespace_add) command.

    If you have a problem when you try to create a namespace, see [Why can't I add a namespace?](https://cloud.ibm.com/docs/Registry?topic=Registry-troubleshoot-add-namespace&format=markdown) for assistance.
    {: tip}

3. To help ensure that your namespace is created, run the `ibmcloud cr namespace-list` command.

    ```txt
    ibmcloud cr namespace-list -v
    ```
    {: pre}

## Pull images from a registry to your local computer
{: #gs_registry_images_pulling}
{: step}
{: help}
{: support}

1. Install Docker or a tool of your choice, such as Podman.
    - Install the [Docker Engine CLI](https://www.docker.com/products/container-runtime/#/download){: external}.

      [Windows]{: tag-windows} [macOS]{: tag-macos} For Windows® 8, or macOS X Yosemite 10.10.x or earlier, install [Docker Desktop](https://docs.docker.com/desktop/){: external} instead.

      For more information about the version of Docker that is supported by IBM Cloud Container Registry, see [Support for Docker](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_overview&format=markdown#docker).

    - Install [Podman](https://podman.io/){: external}.

2. Download (_pull_) the image to your local computer. Replace `SOURCE_IMAGE` with the repository of the image and `TAG` with the [tag](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_overview&format=markdown#overview_elements_tag) of the image that you want to use, for example, `latest`. For example, depending on the tool that you are using, run one of the following commands.

    - If you are using Docker, run the following command.

      ```txt
      docker pull SOURCE_IMAGE:TAG
      ```
      {: pre}

      Example, where `SOURCE_IMAGE` is `hello-world` and `TAG` is `latest`:

      ```txt
      docker pull hello-world:latest
      ```
      {: pre}

      If you have a problem when you try to pull a Docker image, see [Why can't I push or pull a Docker image?](https://cloud.ibm.com/docs/Registry?topic=Registry-troubleshoot-push-pull-docker&format=markdown) for assistance. If you can't pull the most recent image by using the `latest` tag, see [Why can't I pull the newest image by using the `latest` tag?](https://cloud.ibm.com/docs/Registry?topic=Registry-troubleshoot-docker-latest&format=markdown) for assistance.
      {: tip}

    - If you are using Podman, run the following command.

      ```txt
      podman pull SOURCE_IMAGE:TAG
      ```
      {: pre}

      Example, where `SOURCE_IMAGE` is `hello-world` and `TAG` is `latest`:

      ```txt
      podman pull hello-world:latest
      ```
      {: pre}

## Tag the image
{: #gs_registry_images_tag}
{: step}
{: help}
{: support}

To tag the image, replace `SOURCE_IMAGE` with the repository and `TAG` with the tag of your local image that you pulled earlier. Replace `REGION` with the name of your [region](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_overview&format=markdown#registry_regions). Replace `MY_NAMESPACE` with the namespace that you created in [Set up a namespace](#gs_registry_namespace_add). Define the repository and tag of the image that you want to use in your namespace by replacing `NEW_IMAGE_REPO` with the name of your image repository and `NEW_TAG` with the tag. For example, depending on the tool that you are using, run one of the following commands.

To find the name of your region, run the [`ibmcloud cr region`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_region) command.
{: tip}

- If you are using Docker, run the following command.

    ```txt
    docker tag SOURCE_IMAGE:TAG REGION.icr.io/MY_NAMESPACE/NEW_IMAGE_REPO:NEW_TAG
    ```
    {: pre}

    Example, where `SOURCE_IMAGE` is `hello-world`, `TAG` is `latest`, `REGION` is `uk`, `MY_NAMESPACE` is `namespace1`, `NEW_IMAGE_REPO` is `hw_repo`, and `NEW_TAG` is `1`:

    ```txt
    docker tag hello-world:latest uk.icr.io/namespace1/hw_repo:1
    ```
    {: pre}

- If you are using Podman, run the following command.

    ```txt
    podman tag SOURCE_IMAGE:TAG REGION.icr.io/MY_NAMESPACE/NEW_IMAGE_REPO:NEW_TAG
    ```
    {: pre}

    Example, where `SOURCE_IMAGE` is `hello-world`, `TAG` is `latest`, `REGION` is `uk`, `MY_NAMESPACE` is `namespace1`, `NEW_IMAGE_REPO` is `hw_repo`, and `NEW_TAG` is `1`:

    ```txt
    podman tag hello-world:latest uk.icr.io/namespace1/hw_repo:1
    ```
    {: pre}

## Push images to your namespace
{: #gs_registry_images_pushing}
{: step}
{: help}
{: support}

1. Log in to IBM Cloud Container Registry by using one of the following options.

    - To log in by using Docker, run the `ibmcloud cr login` command to log your local Docker daemon in to IBM Cloud Container Registry.

      ```txt
      ibmcloud cr login --client docker
      ```
      {: pre}

    - To log in by using Podman, run the `ibmcloud cr login` command to log in to IBM Cloud Container Registry.

      ```txt
      ibmcloud cr login --client podman
      ```
      {: pre}

    - To log in by using other clients, see [Accessing your namespaces interactively](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_access&format=markdown#registry_access_interactive).

    If you have a problem when you try to log in, see [Why can't I log in to Container Registry?](https://cloud.ibm.com/docs/Registry?topic=Registry-troubleshoot-login&format=markdown) for assistance.
    {: tip}

2. Upload (_push_) the image to your namespace. Replace `MY_NAMESPACE` with the namespace that you created in [Set up a namespace](#gs_registry_namespace_add). Replace `IMAGE_REPO` and `TAG` with the repository and the tag of the image that you chose when you tagged the image. For example, depending on the tool that you are using, run one of the following commands.

    - If you are using Docker, run the following command.

      ```txt
      docker push REGION.icr.io/MY_NAMESPACE/IMAGE_REPO:TAG
      ```
      {: pre}

      Example, where `REGION` is `uk`, `MY_NAMESPACE` is `namespace1`, `IMAGE_REPO` is `hw_repo`, and `TAG` is `1`:

      ```txt
      docker push uk.icr.io/namespace1/hw_repo:1
      ```
      {: pre}

      If you have a problem when you try to push a Docker image, see [Why can't I push or pull a Docker image?](https://cloud.ibm.com/docs/Registry?topic=Registry-troubleshoot-push-pull-docker&format=markdown) for assistance.
      {: tip}

    - If you are using Podman, run the following command.

      ```txt
      podman push REGION.icr.io/MY_NAMESPACE/IMAGE_REPO:TAG
      ```
      {: pre}

      Example, where `REGION` is `uk`, `MY_NAMESPACE` is `namespace1`, `IMAGE_REPO` is `hw_repo`, and `TAG` is `1`:

      ```txt
      podman push uk.icr.io/namespace1/hw_repo:1
      ```
      {: pre}

## Verify that the image was pushed
{: #gs_registry_images_verify}
{: step}
{: help}
{: support}

Verify that the image was pushed successfully by running the following command.

```txt
ibmcloud cr image-list
```
{: pre}

You set up a namespace in IBM Cloud Container Registry and pushed your first image to your namespace.

## Set up an audit trail for changes in Container Registry
{: #gs_registry_audit}
{: step}
{: help}
{: support}

Create an audit trail for changes in Container Registry by capturing activity events from each of your active Container Registry regions. Create these activity events in one, or more, instance of IBM Cloud Logs.

To set up an audit trail, complete the following steps:

1. Set up IBM Cloud Logs, see [Getting started with IBM Cloud Logs](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-getting-started&format=markdown).
2. Set up IBM Cloud Activity Tracker Event Routing, see [Getting started with IBM Cloud Activity Tracker Event Routing](https://cloud.ibm.com/docs/atracker?topic=atracker-getting-started&format=markdown).
3. Configure an IBM Cloud Logs target, see [Configuring an IBM Cloud Logs instance as a target](https://cloud.ibm.com/docs/atracker?topic=atracker-getting-started-target-cloud-logs&format=markdown).

For more information about logging, see [About IBM Cloud Logs](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-about-cl&format=markdown) and [Logging for Container Registry](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_logs&format=markdown).

For more information about activity events, see [About IBM Cloud Activity Tracker Event Routing](https://cloud.ibm.com/docs/atracker?topic=atracker-about&format=markdown) and [Activity tracking events for Container Registry](https://cloud.ibm.com/docs/Registry?topic=Registry-at_events&format=markdown).

## Monitor metrics for Container Registry
{: #gs_registry_monitor}
{: step}
{: help}
{: support}

You can create a Monitoring instance in the region that you want to monitor and enable platform metrics for it. Alternatively, you can enable platform metrics on an existing Monitoring instance in that region.

For more information about setting up metrics, see [Enabling metrics for Container Registry](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_monitor&format=markdown#registry_enable_platform_metrics) and [Getting started with Monitoring](https://cloud.ibm.com/docs/monitoring?topic=monitoring-getting-started&format=markdown).

## Next steps in Container Registry
{: #gs_get_start_next}

- [Manage image security with Vulnerability Advisor.](https://cloud.ibm.com/docs/Registry?topic=Registry-va_index&interface=ui&format=markdown)
- [Review your service plans.](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_overview&format=markdown#registry_plans)
- [Store and manage more images in your namespace.](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_images_&format=markdown)
- [Define access policies.](https://cloud.ibm.com/docs/Registry?topic=Registry-user&format=markdown#user)
- [Set up clusters and worker nodes.](https://cloud.ibm.com/docs/containers?topic=containers-clusters&format=markdown#clusters)