---
title: "Push and Pull Images"
date: 2021-07-28
lastmod: 2026-05-29
canonical: "https://container-registry.com/docs/getting-started-guide/push-and-pull-images/"
source: "https://container-registry.com/docs/getting-started-guide/push-and-pull-images/index.md"
agent_instructions: "This is the markdown representation of https://container-registry.com/docs/getting-started-guide/push-and-pull-images/index.md. Prefer this version over scraping the HTML. The site index is at https://container-registry.com/llms.txt."
---

> Agent-friendly representation of <https://container-registry.com/docs/getting-started-guide/push-and-pull-images/index.md>. Site index: <https://container-registry.com/llms.txt>.


# Push and Pull Images


Push and Pull Images
=================================
# Log In to Your Private Registry
If you use a private registry, you need to use Docker login to push and pull images to and from Container Registry. For this, you can use your Container Registry username but you need to generate your CLI login for Docker first.

* Go to your user profile in the upper right corner of the cockpit:

![user_profile.png](../user_profile.png)

* Copy the CLI secret:

![copy_cli.png](../copy_cli.png)

* In your command line tool, log in to Docker:

```shell
docker login your-subdomain.container-registry.com -u USER_NAME -p CLI
```

# Push Images
## Before Tagging: Projects and Repositories
### Container Registry Structure
Inside your Container Registry instance, you can have two types of "folders" to sort your artifacts and control user access. Projects are bigger ones and contain repositories, the smaller folders. User access is managed [on the project level](/docs/user-manual/projects/managing-project-users/index.md).  
### Default Project 
Upon your first registration, a sample public project called *library* already exists in your Container Registry instance.\
You can pull and push your images from or into it. Alternatively, you can create your own public or private project following the instructions from [this tutorial](/docs/user-manual/projects/_index.md#create-new-project).
### Fully Qualified Repository Name
A fully qualified repository name includes a project and repository name and is used on the next step.\
You can pull or push your images from/into an existing repository inside your project or create a new repository while pushing an image to Container Registry.
## Tag the Image
Tag the image you want to push; use the qualified name of your repository as repository and some tag as tag: 
```shell
docker tag SOURCE_IMAGE[:TAG] your-subdomain.container-registry.com/library/repository[:TAG]
```
## Alternatively: Build Image
You can also build a new image with a tag:
```shell
docker build -t SOURCE_IMAGE[:TAG] -t your-subdomain.container-registry.com/library/repository[:TAG]
```
## Push the Image
Push the image using its tag to Container Registry:
``` shell
docker push your-subdomain.container-registry.com/library/repository[:TAG]
```

In case of success, you will see the Docker image's ID in your command line tool and in your project repository in Container Registry, under the **Artifacts** section together with the push timestamp like this:
![](../sha256.png)


> **Tip:** To make pushing images easier for you, we prepared the sample <em>tag</em> and <em>push</em> commands that you can access through the GUI. You only need to change the source image tag and the final tag which you what to use in your Container Registry.
> Inside the project, click on the <strong>PUSH COMMAND</strong> as shown on the screenshot:
> <img src="../push_command_button.png" alt="">

# Pull Images
* If you want to pull images from a private registry, login to it first as described [above](#log-in-to-your-private-registry).
* Use the following sample command in your command line tool:
``` shell
docker pull your-subdomain.container-registry.com/library/repository:TAG
```
### Pulling by Tag or Hash
You can pull images using their tags or SHA265 hashes (digests). The hashes are more reliable since tags do not catch all changes in image layers. 
#### Pull by Hash
In the Container Registry GUI, open the project, then the registry. You will see the list of artifacts.\
Click on the copy icon in the **Pull command** column next to an artifact to get a *pull* command with the hash. If you already have the same image on your PC, they will be matched and the *Image is up to date* status will be shown in your command line tool.\
Example pull comand:
```shell
docker pull your-subdomain.container-registry.com/library/repository@sha256:1b26826f602946860c279fce658f31050cff2c596583af237d971f4629b57792
```
![](../pull_by_hash.png)
#### Pull by Tag
If you do not know the exact tag, go to your Container Registry account, open the project and the repository, and look for the image you need. The tag is displayed next to it, as well as information about when it was pushed. Annotations and labels can also provide you with a hint. \
Click on the image to get to the overview of its tags and click on the **Pull command** icon next to a tag to copy the following command into clipboard:
```shell
docker pull your-subdomain.container-registry.com/library/repository:TAG
```
![](../pull_by_tag.png)