---
name: Registry-registry_setup_cli_namespace
title: Setting up the Container Registry CLI and namespace
description: To manage your Docker images in IBM Cloud® Container Registry, you must install the `container-registry` command-line interface (CLI) plug-in and create a namespace in a resource group.
last-updated: 2025-12-18
---

> ## 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.

# Setting up the Container Registry CLI and namespace
{: #registry_setup_cli_namespace}

To manage your Docker images in IBM Cloud® Container Registry, you must install the `container-registry` command-line interface (CLI) plug-in and create a [namespace](#x2031005){: term} in a [resource group](#x2161955){: term}.
{: shortdesc}

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}

To add and remove namespaces, you must have the Manager role at the account level, see [Access roles for configuring IBM Cloud Container Registry](https://cloud.ibm.com/docs/Registry?topic=Registry-iam&format=markdown#access_roles_configure).
{: requirement}

Before you begin, install the IBM Cloud CLI, see [Getting started with the IBM Cloud CLI](https://cloud.ibm.com/docs/cli?topic=cli-getting-started&format=markdown).

## Installing the `container-registry` CLI plug-in
{: #cli_namespace_registry_cli_install}
{: help}
{: support}

Install the `container-registry` CLI plug-in so that you can use the command-line interface to manage your namespaces and Docker images in IBM Cloud Container Registry.

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).

2. Optional: [Configure your Docker client to run commands without root permissions](https://docs.docker.com/engine/install/linux-postinstall/){: external}. If you do not do this step, you must run `ibmcloud login`, `ibmcloud cr login`, `docker pull`, and `docker push` commands with `sudo` or as root.

IBM Cloud Container Registry supports Docker and other clients. 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).
{: tip}

You can now [set up your own namespace](#registry_namespace_setup) in IBM Cloud Container Registry.

## Updating the `container-registry` CLI plug-in
{: #registry_cli_update}
{: help}
{: support}

You might want to update the `container-registry` CLI plug-in periodically to use new features.

### Updating `container-registry` CLI plug-in version 1.0
{: #registry_cli_update_v1}
{: help}
{: support}

To update version 1.0 of the Container Registry CLI, run the following command:

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

### Updating `container-registry` CLI plug-in version 0.1
{: #registry_cli_update_v0}
{: help}
{: support}

To update version 0.1 of the Container Registry CLI, run the following command, where `VERSION_NUMBER` is the number of the version of the CLI.

Version 0.1 of the Container Registry CLI is deprecated.
{: deprecated}

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

For example, to update the CLI to version 0.1.584, run the following command:

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

## Uninstalling the `container-registry` CLI plug-in
{: #registry_cli_uninstall}
{: help}
{: support}

If you don't want to use Container Registry anymore, you can delete it by uninstalling the `container-registry` CLI plug-in.

To uninstall the `container-registry` CLI plug-in, run the following command:

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

## Planning namespaces
{: #registry_setup_cli_namespace_plan}

IBM Cloud Container Registry provides a multi-tenant private image [registry](#x2064940){: term} that is hosted and managed by IBM. You can store and share your Docker images in this registry by setting up a registry namespace.

IAM access permissions can be granted at the account level, for all namespaces, or on the namespace itself. It's also possible to grant access at the resource group level. Namespaces are created in a resource group, which cannot be changed, so that you can grant access at the resource group level. If you don't specify a resource group, and a resource groups isn't targeted, the default resource group is assigned when the namespace is created.

If you have an older namespace that isn't in a resource group, you can assign it to a resource group and then set permissions for that namespace at the resource group level. For more information about resource groups, see [Assigning existing namespaces to resource groups](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_setup_cli_namespace&format=markdown#registry_namespace_assign).

Namespaces that are assigned to a resource group show in the **Resource list** page of the IBM Cloud console.
{: tip}

You can set up multiple namespaces, for example, to have separate repositories for your production and staging environments. If you want to use the registry in multiple IBM Cloud regions, you must set up a namespace for each region. Namespace names are unique within regions. You can use the same namespace name for each region, unless someone else already has a namespace with that name in that region.

You can't share a Container Registry (`icr.io`) namespace across IBM Cloud accounts. A namespace is owned by a single IBM Cloud account and cannot be shared with multiple accounts.

You can have 100 namespaces in each region.
{: note}

To work with the IBM-provided public images only, you do not need to set up a namespace.

If you're unsure whether a namespace is already set for your account, run the `ibmcloud cr namespace-list` command with the `-v` option to retrieve existing namespace information.
{: tip}

Consider the following rules when you choose a namespace:

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

Do not put personal information in your namespace names.
{: important}

After you set your first namespace, you're assigned to the free IBM Cloud Container Registry service plan unless you [upgrade your plan](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_overview&format=markdown#registry_plan_upgrade).

### User permissions for working with namespaces
{: #registry_setup_cli_namespace_plan_perm}
{: help}
{: support}

You can control which users can work with namespaces by using IAM roles.

- To add, assign, and remove namespaces, you must have the Manager role in the IBM Cloud Container Registry service at the account level, see [Access roles for configuring IBM Cloud Container Registry](https://cloud.ibm.com/docs/Registry?topic=Registry-iam&format=markdown#access_roles_configure).

    - To add and assign namespaces, you must also have the Viewer platform role for the resource group in which you want to create the namespace. To assign the Viewer role for a resource group to a user, run the following [`ibmcloud iam user-policy-create`](https://cloud.ibm.com/docs/cli?topic=cli-ibmcloud_commands_iam&format=markdown#ibmcloud_iam_user_policy_create) command, where `USER` is the name of the user and `RESOURCE_GROUP_ID` is the resource group ID:

        ```txt
        ibmcloud iam user-policy-create USER --roles Viewer --resource-type resource-group --resource RESOURCE_GROUP_ID
        ```
        {: pre}

- To view and analyze namespaces, you must have the Reader or Manager role in the IBM Cloud Container Registry service, see [Access roles for using IBM Cloud Container Registry](https://cloud.ibm.com/docs/Registry?topic=Registry-iam&format=markdown#access_roles_using).

For more information about user roles, [Defining IAM access policies](https://cloud.ibm.com/docs/Registry?topic=Registry-user&format=markdown#user).

## Setting up a namespace
{: #registry_namespace_setup}
{: help}
{: support}

You must create a namespace to store your Docker images in IBM Cloud Container Registry.

Before you begin, complete the following tasks:

- [Install the IBM Cloud CLI and the `container-registry` CLI plug-in](https://cloud.ibm.com/docs/Registry?topic=Registry-getting-started&format=markdown#gs_registry_cli_install).
- [Plan how to use and name your registry namespaces](#registry_setup_cli_namespace_plan).

To create a namespace, see [Set up a namespace](https://cloud.ibm.com/docs/Registry?topic=Registry-getting-started&format=markdown#gs_registry_namespace_add). Namespaces are created in the resource group 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 a resource group isn't targeted, the default resource group is used. For more information about resource groups, see [Managing resource groups](https://cloud.ibm.com/docs/account?topic=account-rgs&format=markdown).

Namespaces that are assigned to a resource group show in the **Resource list** page of the IBM Cloud console.

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}

You can now [push Docker images to your namespace in IBM Cloud Container Registry](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_images_&format=markdown#registry_images_pushing_namespace) and share these images with other users in your account. To control access to namespaces in IBM Cloud IAM, see [Creating policies](https://cloud.ibm.com/docs/Registry?topic=Registry-user&format=markdown#create).

## Assigning existing namespaces to resource groups
{: #registry_namespace_assign}
{: help}
{: support}

Namespaces created in version 0.1.484 of the CLI or earlier and in the IBM Cloud console before 29 July 2020, aren't assigned to resource groups. If you have a namespace that isn't assigned to a resource group, you can assign the namespace to a resource group and then set permissions for that namespace at the resource group level.

You can assign a namespace to a resource group only once. When a namespace is in a resource group, you can't move it to another resource group.
{: note}

You can assign an existing namespace to a resource group by using the [`ibmcloud cr namespace-assign`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#ic_cr_namespace_assign) command. To find out which namespaces are assigned to resource groups and which are unassigned, run the [`ibmcloud cr namespace-list`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_namespace_list) command with the `-v` option.

Namespaces that are assigned to a resource group show in the **Resource list** page of the IBM Cloud console.

If the namespaces don't all show in the **Resource list** page, see [Why don't all my namespaces show in the Resource list?](https://cloud.ibm.com/docs/Registry?topic=Registry-troubleshoot-namespace-resource-list&format=markdown) for assistance.
{: tip}

For more information about resource groups, see [Creating a resource group](https://cloud.ibm.com/docs/account?topic=account-rgs&interface=ui&format=markdown#create_rgs).

To assign an existing namespace to a resource group, complete the following steps:

1. Log in to IBM Cloud.

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

2. To find the namespace, list the available namespaces.

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

3. Assign the namespace to a resource group.

    Replace `MY_RESOURCE_GROUP` with the name or ID of the resource group and `MY_NAMESPACE` with the name of the namespace.

    ```txt
    ibmcloud cr namespace-assign -g MY_RESOURCE_GROUP MY_NAMESPACE
    ```
    {: pre}

## Removing namespaces
{: #registry_remove}
{: help}
{: support}

If you no longer require a registry namespace, you can remove the namespace from your IBM Cloud account.

1. Log in to IBM Cloud.

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

2. List available namespaces.

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

3. Remove a namespace.

    When you remove a namespace, any images that are stored in that namespace are also deleted. This action cannot be undone.
    {: attention}

    Replace `MY_NAMESPACE` with the namespace that you want to remove.

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

    After you delete a namespace, it might take a few minutes before that namespace becomes available again to reuse.