Push a Docker Plugin to a Registry with docker plugin push

You will finish with a checked command for publishing an existing Docker plugin to Docker Hub or a private registry. The examples use Docker CLI 29.8.1 from package docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble. Allow about ten minutes, plus the time needed to authenticate and upload the plugin. You need a local plugin, access to the Docker daemon, a registry repository where you can push, and credentials for that registry.

1. Confirm the installed command

Start with the read-only help output. It confirms the syntax supported by the installed CLI:

$ docker plugin push --help
Usage:  docker plugin push [OPTIONS] PLUGIN[:TAG]

Push a plugin to a registry

The local manpage documents the same form and does not list any command-specific options. The argument is a plugin reference, optionally followed by a tag. Do not copy image-push options such as --quiet or --all-tags into this command: they are not part of the installed docker plugin push interface.

2. Find the exact local plugin reference

List plugins before logging in or pushing:

$ docker plugin ls
ID             NAME                         DESCRIPTION           ENABLED
PLUGIN_ID      EXAMPLE_USER/example:1.0     Example plugin        false

Your output will differ. Use the value in the NAME column, not the ID, and check the registry namespace. A plugin reference such as EXAMPLE_USER/example:1.0 targets the example repository under EXAMPLE_USER. If the name has no explicit tag, Docker uses the normal latest convention for the reference, but an explicit release tag is easier to review.

For a machine-readable check, ask the CLI to print only the plugin name and reference:

$ docker plugin ls --format '{{.Name}} {{.PluginReference}}'
EXAMPLE_USER/example:1.0 docker.io/EXAMPLE_USER/example:1.0

The reference is host-specific, so do not treat the sample output as something to paste. If the plugin is missing, stop here and create it first with a separate, reviewed workflow. A plugin does not need to be enabled merely to publish it; the important prerequisite is that it exists locally and is ready for distribution.

3. Authenticate to the destination registry

Docker registry credentials are managed by docker login. Log in to the registry named by the plugin reference, using an ordinary account with permission to push to that repository:

$ docker login docker.io
Username: EXAMPLE_USER
Password: [enter a token without displaying it]
Login Succeeded

For a private registry, replace docker.io with its hostname, for example registry.example.net. Do not put a password or access token in the command line: shells can expose command arguments through history and process inspection. Prefer a short-lived token with only the repository permissions required. Docker stores the resulting credential according to the client configuration, so review your organisation's credential-helper policy before authenticating on a shared machine.

4. Review the exact push command

Set the reference as a shell variable so you can inspect one value and reuse it without retyping:

$ PLUGIN_REF='EXAMPLE_USER/example:1.0'
$ printf 'about to push: %s\n' "$PLUGIN_REF"
about to push: EXAMPLE_USER/example:1.0

Replace the placeholder with the reference from your own docker plugin ls output. Confirm all three parts when present: registry hostname, namespace or account, and tag. A typo can target a different repository or produce a confusing authentication error.

This is the state-changing step. It needs permission to contact the Docker daemon and network access to the registry. On Linux, daemon access may be available to root or to users in the configured Docker group. Do not add sudo automatically: use the access method already approved for this host, because membership of the Docker group is effectively privileged access to the daemon.

5. Push and read the result

When the reference is correct, run:

$ docker plugin push "$PLUGIN_REF"
The push refers to repository [docker.io/EXAMPLE_USER/example]
1.0: pushed
1.0: digest: sha256:EXAMPLE_DIGEST size: EXAMPLE_SIZE

The progress text and digest are registry-dependent, so do not script against the sample wording. The useful result is an exit status of zero and a completed push. Capture that status immediately if a script needs to make a decision:

$ status=$?
$ printf 'push exit status: %s\n' "$status"
push exit status: 0

A non-zero status means the operation did not complete successfully. Common causes are a missing local plugin, an incorrect namespace or tag, an expired login, insufficient repository permission, an unreachable registry, or a registry that does not support the required plugin distribution. Read the first error carefully before retrying. Repeated retries do not fix a wrong destination.

6. Verify without changing the local plugin

Inspect the local plugin again after a successful push:

$ docker plugin ls --format '{{.Name}} {{.PluginReference}}'
EXAMPLE_USER/example:1.0 docker.io/EXAMPLE_USER/example:1.0

The local listing should still show the same plugin reference. Publishing does not enable, disable, remove or reconfigure the local plugin. To verify the remote side, use the registry's normal repository or tag view, or ask another authorised Docker host to inspect the reference. A remote verification should use the exact tag and digest reported by the push, not just the repository name.

There is no rollback command in docker plugin push. If you published the wrong tag, leave the correct tag available and follow the registry's reviewed retention or deletion process. Do not remove the local plugin as a reaction to a remote naming mistake; docker plugin rm would change local state and is unrelated to undoing a registry upload.