psviderski/unregistry — an image tool — sits at 4.9k GitHub stars in the Image Tools space. Push docker images directly to remote servers without an external registry
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
▸ Push docker images directly to remote servers without an external registry ◂
Unregistry is a lightweight container image registry that stores and serves images directly from your Docker daemon's
storage.
The included docker pussh command (extra 's' for SSH) lets you push images straight to remote Docker servers over SSH.
It transfers only the missing layers, making it fast and efficient.
You've built a Docker image locally. Now you need it on your server. Your options suck:
Docker Hub / GitHub Container Registry - Your code is now public, or you're paying for private repos
Self-hosted registry - Another service to maintain, secure, and pay for storage
Save/Load - docker save | ssh <remote server> docker load transfers the entire image, even if 90% already exists
on the server
Rebuild remotely - Wastes time and server resources. Plus now you're debugging why the build fails in production
You just want to move an image from A to B. Why is this so hard?
The solution
docker pussh myapp:latest user@server
That's it. Your image is on the remote server. No registry setup, no subscription, no intermediate storage, no exposed
ports. Just a direct transfer of the missing layers over SSH.
Here's what happens under the hood:
Establishes SSH tunnel to the remote server
Starts a temporary unregistry container on the server
Forwards a random localhost port to the unregistry port over the tunnel
docker push to unregistry through the forwarded port, transferring only the layers that don't already exist
remotely. The transferred image is instantly available on the remote Docker daemon
Stops the unregistry container and closes the SSH tunnel
It's like rsync for Docker images — simple and efficient.
[!NOTE]
Unregistry was created for Uncloud, a lightweight tool for deploying
containers across multiple Docker hosts. We needed something simpler than a full registry but more efficient than
save/load.
Requirements
On local machine
Docker CLI with plugin support (Docker 19.03+)
OpenSSH client
On remote server
Docker is installed and running
SSH user has permissions to run docker commands (user is root or non-root user is in docker group — see
Manage Docker as a non-root user
for details)
If sudo is required, ensure the user can run sudo docker without a password prompt
Your server has internet access to ghcr.io to pull the unregistry image
ghcr.io/psviderski/unregistry:latest on first docker pussh use.
If your server requires a proxy to access the internet, configure Docker to use it by following the
Daemon proxy configuration guide.
For air-gapped environments or where the access to ghcr.io is restricted, you can preload the
image manually:
# Get the needed unregistry image version from the plugin version output
docker pussh --version
# Will return:
# ...
# unregistry image: ghcr.io/psviderski/unregistry:X.Y.Z
# On a machine with internet access
docker pull ghcr.io/psviderski/unregistry:X.Y.Z
docker save ghcr.io/psviderski/unregistry:X.Y.Z | ssh user@server docker load
Unregistry container requires access to the containerd socket at /run/containerd/containerd.sock, so the container
runs as root to have the necessary permissions
Installation
macOS/Linux via Homebrew
brew install psviderski/tap/docker-pussh
After installation, to use docker-pussh as a Docker CLI plugin (docker pussh command) you need to create a symlink:
mkdir -p ~/.docker/cli-plugins
# Download the script to the docker plugins directory
curl -sSL https://raw.githubusercontent.com/psviderski/unregistry/v0.4.3/docker-pussh \
-o ~/.docker/cli-plugins/docker-pussh
# Make it executable
chmod +x ~/.docker/cli-plugins/docker-pussh
If you want to download and use the latest version from the main branch:
Windows is not currently supported, but you can try using WSL 2
with the above Linux instructions.
Verify installation
docker pussh --help
⚠️ Containerd image store configuration
Unregistry stores images directly in containerd's image store, which is the underlying container runtime used by Docker.
However, by default, Docker maintains its own separate storage layer and doesn't directly use images from containerd.
When you enable containerd image store in Docker, it allows Docker
to directly use the same images that unregistry stores in containerd, eliminating duplication.
With containerd image store enabled (recommended)
Images pushed through unregistry are immediately available to Docker
No additional storage space is used (images are stored once in containerd)
Faster pussh operations without the additional pull step from unregistry to the classic Docker image store
Without containerd image store (default Docker behaviour)
After pushing, pussh runs an additional docker pull on the remote host to pull the image from unregistry to make
it available to Docker
Images are stored twice: once in containerd (by unregistry) and once in the classic Docker image store
These unmanaged images in containerd can fill up disk space over time. To manage them manually, use:
Please refer to the official Docker documentation:
Enable containerd image store on Docker Engine.
[!WARNING]
Switching to containerd image store causes you to temporarily lose images and containers created using the classic
storage driver. Those resources still exist on your filesystem, and you can retrieve them by turning off the
containerd image store feature.
Usage
Push an image to a remote server. Please make sure the SSH user has permissions to run docker commands (user is
root or non-root user is in docker group). If sudo is required, ensure the user can run sudo docker without a
password prompt.
Distribute images in isolated networks that can't access public registries over the internet.
Advanced usage
Running unregistry standalone
Sometimes you want a local registry without the overhead. Unregistry works great for this:
# Run unregistry locally and expose it on port 5000
docker run -d -p 5000:5000 --name unregistry \
-v /run/containerd/containerd.sock:/run/containerd/containerd.sock \
ghcr.io/psviderski/unregistry
# Use it like any registry
docker tag myapp:latest localhost:5000/myapp:latest
docker push localhost:5000/myapp:latest
Custom SSH options
Need custom SSH settings? Use the standard SSH config file, or pass a specific config with -F:
# ~/.ssh/config
Host prod-server
HostName server.example.com
User deploy
Port 2222
IdentityFile ~/.ssh/deploy_key
# Now just use
docker pussh myapp:latest prod-server
# Or use an alternate config file
docker pussh myapp:latest prod-server -F ~/.ssh/config.prod
Third-party projects
https://github.com/SonOfBytes/unregistry-action - GitHub Action to push Docker images to remote servers using
docker-pussh plugin for Docker CLI
https://github.com/RezaKargar/setup-unregistry - GitHub Action to install docker-pussh plugin for Docker CLI
https://github.com/iloveitaly/docker-image-cleanup - Python tool to manage Docker images in self-hosted registries by
automatically removing outdated images while preserving recent and actively used ones
Contributing
Found a bug or have a feature idea? We'd love your help!
🐛 Found a bug? Open an issue
💡 Have questions, ideas, or need help?
Start a discussion or join an existing one in
the Discussions.
Join the Uncloud Discord community where we discuss features, roadmap,
implementation details, and help each other out.
Inspiration & acknowledgements
Spegel - P2P container image registry that inspired me to implement a registry
that uses containerd image store as a backend.
Docker Distribution - the bulletproof Docker registry implementation
that unregistry is based on.
Built with ❤️ by Pasha Sviderski who just wanted to deploy his images
How active is development on psviderski/unregistry?
The most recent commit recorded on psviderski/unregistry was 4 months ago, based on the GitHub push timestamp. The repository has 97 forks — one of the better signals of community interest.
How many stars does psviderski/unregistry have?
psviderski/unregistry has 4.9k GitHub stars — refresh the page for the live number, or check github.com/psviderski/unregistry. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
What else is in the Image Tools space?
psviderski/unregistry is tracked by TopGit under the Image Tools category, alongside 7 GitHub-tagged topics. Trending and Topics pages list peer repositories of comparable stars and language.
What language is psviderski/unregistry written in?
psviderski/unregistry is written primarily in Go. GitHub's language field is based on the largest share of bytes in the default branch.
What topics is psviderski/unregistry associated with?
GitHub's repository topics for psviderski/unregistry: "containerd", "docker", "golang", "kubernetes", "oci", "registry", "uncloud". TopGit's editorial category is Image Tools.
Where do I read more about psviderski/unregistry?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/psviderski/unregistry is the definitive source.
Why is psviderski/unregistry categorized under Image Tools?
TopGit places psviderski/unregistry in the Image Tools category based on its GitHub topics and description (tagged: "containerd", "docker", "golang"). Categories are assigned from real repository metadata, not editorial guesswork.
Read full README in the tab above.
Want a second opinion on unregistry?
Ask an AI that can read this page — one click and you get its take on unregistry.