---
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:


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:


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.


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:

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

       $ sudo systemctl restart podman

- Linux (rootless)

- Stop all Podman processes.

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