owned this note
owned this note
Published
Linked with GitHub
---
sidebar_position: 3
title: Registries
description: Working with container registries
tags: [podman-desktop, containers]
keywords: [podman desktop, podman, containers, registries]
hide_table_of_contents: false
---
# Setting up container registries
## Overview
Podman Desktop allows you to configure Podman container registries from its graphical user interface: no need to use the command line interface.
### Who is this for
If you are a developer who deals with containers, often finds yourself pulling and pushing container images – this tutorial is tailor-made for you!
### What will you gain
By the end of this tutorial, you'll be able to:
- Set up a pre-configured container registry.
- Set up a custom container registry.
- Set up a custom container registry with an insecure certificate, such as a self-signed certificate.
- Verify your registry is properly configured.
- Change your registry credentials.
- Remove a registry configuration.
- Understand how Podman Desktop and Podman are handling the registry configuration.
## Before you start
Before you start the tutorial, you should:
- Have a running Podman environment:
- Podman machine on Windows and macOS.
- Native Podman on Linux.
- Get authentication details for your container registry:
- Registry URL.
- User name.
- Password or OAuth secret.
## Setting up a pre-configured container registry
To ease usage of the most popular container registries, Podman Desktop has pre-configured registries, including:
- Docker Hub
- Red Hat Quay
- GitHub
- Google Container Registry
If your container registry is in this list, follow the steps:
1. Go to **<icon icon="fa-solid fa-cog" size="lg" /> Settings > Registries**.
2. In your registry line, click **Configure**.
3. Enter your registry credentials:
![Authenticating to a pre-configured registry](img/authenticating-to-a-preconfigured-registry.png)
1. **Username**: Enter your user name.
2. **Password**: Enter your password or OAuth secret.
3. Click **Login**.
Podman Desktop logs Podman in with the provided credentials.
If you enter the wrong credentials, you see an error message: enter the correct credentials, and click **Login** again.
## Setting up a custom container registry
You have a custom container registry, or one that is not available in the pre-configured list: we have got you covered. Follow the steps:
1. Go to **<icon icon="fa-solid fa-cog" size="lg" /> Settings > Registries**.
1. Click **<icon icon="fa-solid fa-plus-circle" size="lg" /> Add registry** at the top right corner of the screen.
1. Enter your registry details:
![Adding a custom registry](img/adding-a-custom-registry.png)
1. **Registry Location**: Enter your repository URL, such as `https://myregistry.tld`.
2. **Username**: Enter your user name.
3. **Password**: Enter your password or OAuth secret.
4. Click **Login**.
Podman Desktop logs Podman in with the provided credentials.
If you enter the wrong credentials, you see an error message: enter the correct credentials, and click **Login** again.
## Setting up a custom container registry with an insecure certificate
If your registry has an insecure certificate, such as a self-signed certificate, you see a warning when setting up the registry.
![Podman Desktop Registry Warning](img/registry-warning-insecure.png)
1. In the **Invalid Certificate** window, click **Yes** to add the registry anyway.
1. Edit the registry configuration file on your host.
Create the file if does not exists.
- Windows: `$HOME/.config/containers/registries.conf`
- macOS: `$HOME/.config/containers/registries.conf`
- Linux (rootless): `$HOME/.config/containers/registries.conf`
- Linux (rootful): `/etc/containers/registries.conf`
For each insecure registry, add a new `[[registry]]` section defining:
- `location =`: your registry URL.
- `insecure = true`: accept the insecure certificate.
For example, if your registry location is `http://registry.example.com`, add the following lines:
```toml
[[registry]]
location = "registry.example.com"
insecure = true
```
1. Restart Podman to apply the changes.
- Windows and macOS
1. Go to **<icon icon="fa-solid fa-cog" size="lg" /> Settings > Resources**.
2. Restart the Podman machine.
- Linux (rootful)
- Restart Podman.
```shell-session
$ sudo systemctl restart podman
```
- Linux (rootless)
- Stop all Podman processes.
```shell-session
$ pkill podman
```
## Verifying your registry is properly configured
To verify your registry has been properly configured, you can do the following steps:
1. In **<icon icon="fa-solid fa-cog" size="lg" /> Settings > Registries**, the line with your registry has content in the Username and Password column, and action icons replacing the Configure button.
1. Pull a private image from the registry.
1. Get the name of a private image stored in your registry, such as `quay.io/my-repository/my-image`, `ghcr.io/my-repository/my-image`, `docker.io/my-repository/my-image`, or `my-registry.tld/my-repository/my-image`.
1. Go to **Images**.
1. Click **Pull an image**.
1. On the **Image to Pull** screen:
1. **Image to pull**: Enter the image name.
1. Click Pull image.
1. Click Done.
1. Push an image to the registry:
1. Get the fully qualified image name that your registry requires, such as `quay.io/my-repository/my-image`, `ghcr.io/my-repository/my-image`, or `docker.io/my-repository/my-image`.
1. Go to **Images**.
1. Click **Build an image**.
1. On the **Build Image from Containerfile** screen
1. **Containerfile path**: select the Containerfile or Dockerfile to build.
2. **Image Name**: enter the fully qualified image name that your registry requires.
3. Click Build.
4. Click Done.
1. On your image line, click **<Icon icon="fa-solid fa-ellipsis-v" size="lg" />**.
The contextual menu has a **Push Image to _your registry_** entry.
## Changing your registry credentials
To change your registry credentials, you can do the following steps:
1. Go to **<icon icon="fa-solid fa-cog" size="lg" /> Settings > Registries**.
1. On your registry line, click **<Icon icon="fa-solid fa-ellipsis-v" size="lg" />**.
1. Click **Edit password**.
1. Enter your credentials in the **Username** and **Password** fields, and click **Login**.
Podman Desktop logs Podman in with the updated credentials.
## Removing a registry
To remove your registry, you can do the following steps:
1. Go to **<icon icon="fa-solid fa-cog" size="lg" /> Settings > Registries**.
1. On your registry line, click **<Icon icon="fa-solid fa-ellipsis-v" size="lg" />**.
1. Click Remove.
Podman Desktop removes the registry from the settings, and logs Podman out from the registry.
## Understanding the registry configuration
Podman Desktop stores the authentication (auth.json) and registry (registries.conf) configuration files directly on your host.
The Podman machine mounts the configuration files to access it.
When you delete the Podman machine, the registry configuration is not lost: it stays on your host.
## Next steps
Consider completing some other common tasks that depend registries:
- Pulling an image.
- Pushing an image to a registry.