How to Migrate Docker Repositories to a New DockerHub Username

If you’ve ever tried to rename your DockerHub username, you know there’s no direct way to do it. For many users, creating a new DockerHub account and transferring all their repositories is the best option. This guide walks you through automating the process of migrating all Docker images from an old username to a new one. We’ll share a complete shell script, so you don’t have to manually tag and push each image, saving you time and effort.

Why Migrate DockerHub Repositories to a New Username?

Changing usernames is common, whether for rebranding, consistency, or organizational restructuring. However, DockerHub does not yet offer a built-in feature to rename usernames. Instead, this workaround lets you quickly replicate all your public Docker images to a new username with a simple script, making it easy to maintain continuity across projects.

Here’s a shell script that automates the migration of all public Docker images from one username to another. It will pull each image, re-tag it with the new username, and then push it to the new account.

Docker Migration Script

#!/bin/bash

# Source and target usernames
OLD_USER="aoms"      # Replace with the current username
NEW_USER="ataiva"    # Replace with the new username

# Login to DockerHub (only if needed)
docker login -u "$NEW_USER"

# Fetch all repositories for the old user
repos=$(curl -s "https://hub.docker.com/v2/repositories/$OLD_USER/?page_size=100" | jq -r '.results[].name')

# Loop through each repository and migrate it
for REPO in $repos; do
    # Pull the latest image from the old username
    docker pull "$OLD_USER/$REPO:latest"

    # Tag the image with the new username
    docker tag "$OLD_USER/$REPO:latest" "$NEW_USER/$REPO:latest"

    # Push the image to the new username
    docker push "$NEW_USER/$REPO:latest"

    # Optional: remove the old image from the local machine
    docker rmi "$OLD_USER/$REPO:latest" "$NEW_USER/$REPO:latest"

    echo "Migrated $OLD_USER/$REPO to $NEW_USER/$REPO"
done

echo "Migration complete!"

Script Details

• Authentication: The script logs in as the new user. Make sure you have already logged in or can supply credentials when prompted.
• Fetching Repositories: It retrieves a list of all repositories for the old username using the Docker Hub API.
• Loop: It loops through each repository, pulls the latest image, tags it with the new username, and pushes it to the new account.
• Cleanup: After pushing, it optionally removes the local images to save space.

Requirements

• jq: This script uses jq to parse JSON. Install it if it’s not already on your system (sudo apt install jq for Ubuntu, brew install jq for macOS).

Run the Script

Save the script to a file, e.g., migrate_docker_images.sh, and make it executable:

chmod +x migrate_docker_images.sh
./migrate_docker_images.

This script will loop through all public images, transfer them to the new username, and confirm each migration. Let me know if there are any issues or adjustments you’d like!

Don’t forget to bookmark this guide in case you need to migrate Docker images in the future, and check out our other Docker and DevOps articles for more useful scripts and tips.