Docker Hub Status

dockerhub-status lists all repositories and image tags published in a Docker Hub organization. The organization defaults to kaizten.

The report includes repository creation and update dates, total pulls, stars, visibility, status, storage size, and every tag. Tag details include the last push, update and pull timestamps, compressed size, status, digest, and platforms.

Docker Hub exposes pull counts per repository, not per tag. Because tags can be overwritten, the tag publication value is the latest push timestamp supplied by Docker Hub rather than an immutable first-publication date.

Requirements

• Python 3.10 or newer
• Network access to hub.docker.com

The package has no third-party runtime dependencies.

Usage

Run the source-tree script with the default organization:

./dockerhub-status.py

Select another organization:

./dockerhub-status.py --organization docker

Print structured JSON:

./dockerhub-status.py --format json

Skip tag requests for a faster repository-only summary:

./dockerhub-status.py --no-tags

After installing the package, use the same options with the console command:

dockerhub-status --organization kaizten

Authentication

Anonymous requests list public repositories. To include private repositories, provide a Docker Hub personal access token (PAT) or organization access token (OAT).

Docker Hub does not accept a PAT or OAT directly in an Authorization: Bearer header. Doing so returns:

Docker Hub API request failed with HTTP 401: A personal access token or organization access token cannot be used as a bearer

dockerhub-status avoids this error by exchanging the PAT/OAT for a short-lived access token at /v2/auth/token. Only that returned access token is sent as a bearer to the namespace API.

Organization access token

For an OAT, the value passed to --organization is also used as the authentication identifier by default:

export DOCKERHUB_TOKEN='your-organization-access-token'
dockerhub-status --organization kaizten

The token can instead be supplied directly on the command line, although an environment variable is less likely to expose it in shell history or process listings:

dockerhub-status \
  --organization kaizten \
  --token 'your-organization-access-token'

Personal access token

For a PAT, set the authentication identifier to your Docker Hub username. The username can differ from the organization being inspected:

export DOCKERHUB_IDENTIFIER='your-dockerhub-username'
export DOCKERHUB_TOKEN='your-personal-access-token'
dockerhub-status --organization kaizten

The same configuration can be provided with command-line options:

dockerhub-status \
  --organization kaizten \
  --identifier 'your-dockerhub-username' \
  --token 'your-personal-access-token'

Docker Hub can also restrict deep anonymous pagination for organizations with many repositories. In that case, authentication is required even when all the requested repositories are public; the command reports the API error instead of silently returning an incomplete list.

Build and publish

Build the wheel and source distribution and validate their metadata:

./build-package.sh

Publish an already built version to PyPI:

./publish-pypi.sh

PyPI does not allow an existing filename/version to be uploaded again. Increase the version in pyproject.toml before publishing a replacement release.