A tool for display statistics about Docker images published on Docker Hub
71
Know how your Docker images are really being used. Docker Hub shows a single number, the total pull count. This image turns it into pulls in the last collection, last 24 hours, 7 days, 30 days and hour by hour, for every public image of your user or organization. You get them in a self-hosted web UI, a JSON API, Prometheus metrics and Grafana dashboards.

| Source code | https://github.com/aeciopires/docker-hub-image-statistics |
| Documentation | https://github.com/aeciopires/docker-hub-image-statistics/tree/main/docs |
| Issues | https://github.com/aeciopires/docker-hub-image-statistics/issues |
| Architectures | linux/amd64, linux/arm64 |
| Port | 8080 (web UI, API, /metrics, health checks) |
| Volume | /data (history: SQLite + JSON) |
| User | 65532 (non-root), distroless base, about 27 MB |
docker pull aeciopires/docker-hub-image-statistics:latest
Docker Hub only keeps a cumulative counter, so it cannot answer simple questions such as "how many pulls did my image get this week?", "what happened in the last hour?" or "did the last release increase adoption?".
This application works like a meter reader: every hour (configurable) it writes down the counter of each image, keeps the history and subtracts the readings to get the pulls of each period.
nginx, grafana/grafana, ...), with include/exclude globs.Retry-After;DHIS_* environment variables and command-line
flags, with built-in defaults. Reload on SIGHUP without restarting;
invalid files are rejected.INFO). Two Grafana dashboards are available./healthz, /readyz) and a built-in healthcheck
command, since the image has no shell or curl.Track your organization (replace myorg) plus a few official images:
docker run -d --name dhis -p 8080:8080 \
--read-only --cap-drop ALL --security-opt no-new-privileges \
-v dhis-data:/data \
-e DHIS_DOCKERHUB_NAMESPACES=myorg \
-e DHIS_DOCKERHUB_REPOSITORIES=nginx,redis \
aeciopires/docker-hub-image-statistics:latest
Open http://localhost:8080. The first collection runs right away. The
"last collection", 24h, 7d and 30d numbers fill in as the history grows, so
keep the /data volume.
curl -s http://localhost:8080/api/v1/summary
curl -s 'http://localhost:8080/api/v1/images?sort=last'
curl -s http://localhost:8080/metrics | grep dockerhub_image_pulls
docker exec dhis docker-hub-image-statistics config # effective config (add -c FILE when using a file)
Mount a directory, not a single file. Editors replace files when saving, and a single-file bind mount keeps showing the old content.
mkdir -p config && cat > config/config.yaml <<'EOF'
dockerhub:
namespaces: [myorg]
repositories: [nginx, grafana/grafana]
exclude: ["*/*-dev"]
collector:
interval: 1h
log:
level: info
EOF
docker run -d --name dhis -p 8080:8080 \
--read-only --cap-drop ALL --security-opt no-new-privileges \
-v dhis-data:/data -v "$PWD/config:/etc/dhis:ro" \
aeciopires/docker-hub-image-statistics:latest serve --config /etc/dhis/config.yaml
Every option is described in the configuration guide.
Edit config/config.yaml, then:
docker kill --signal HUP dhis
docker logs dhis | tail -2 # "configuration reloaded" or "configuration reload rejected"
An invalid file is rejected and the running configuration is kept.
POSIX-style short and long flags; flags override environment variables, which override the file:
docker run --rm aeciopires/docker-hub-image-statistics --help
docker run --rm aeciopires/docker-hub-image-statistics --version
docker run -d -p 8080:8080 -v dhis-data:/data aeciopires/docker-hub-image-statistics \
-n myorg,otherorg -r nginx -i 30m -l debug
| Short | Long | Meaning |
|---|---|---|
-c | --config | YAML configuration file |
-n | --namespaces | Users/organizations to discover |
-r | --repositories | Explicit images |
-i | --interval | Collection interval (30m, 1h, 1d) |
-l | --log-level | debug, info, warn, error |
-a | --address | Listen address (default :8080) |
-h | --help | Help (on every command) |
-v | --version | Version |
Commands: serve (default), config, healthcheck, version, completion.
services:
dhis:
image: aeciopires/docker-hub-image-statistics:latest
command: ["serve", "--config", "/etc/dhis/config.yaml"]
ports: ["127.0.0.1:8080:8080"]
environment:
DHIS_DOCKERHUB_USERNAME: ${DHIS_DOCKERHUB_USERNAME:-}
DHIS_DOCKERHUB_TOKEN: ${DHIS_DOCKERHUB_TOKEN:-}
volumes:
- ./config:/etc/dhis:ro
- dhis-data:/data
read_only: true
cap_drop: [ALL]
security_opt: ["no-new-privileges:true"]
restart: unless-stopped
volumes:
dhis-data:
Reload after editing the file: docker compose kill -s SIGHUP dhis.
Every YAML key has a variable: DHIS_ + the key in upper case with . → _.
The most used ones:
| Variable | Default | What it does |
|---|---|---|
DHIS_DOCKERHUB_NAMESPACES | library | Users/organizations to discover (none clears the list) |
DHIS_DOCKERHUB_REPOSITORIES | empty | Extra images (ns/name or name) |
DHIS_DOCKERHUB_USERNAME / DHIS_DOCKERHUB_TOKEN | anonymous | Personal access token: higher API limits and more than 100 repositories per namespace |
DHIS_COLLECTOR_INTERVAL | 1h | How often to collect (minimum 5m anonymous, 1m authenticated) |
DHIS_CACHE_RETENTION | 2160h | History kept (90d also works) |
DHIS_LOG_LEVEL | info | debug, info, warn, error |
DHIS_LOG_FORMAT | json | json or text |
DHIS_TELEMETRY_OTLP_ENDPOINT | empty | OTLP/HTTP endpoint, e.g. http://otel-collector:4318 |
DHIS_TELEMETRY_TRACES / DHIS_TELEMETRY_LOGS | false | Export traces / logs over OTLP |
DHIS_CONFIG_FILE | empty | Configuration file (same as --config) |
Anonymous clients are limited by Docker Hub to 180 API calls per minute per IP and see only the first 100 repositories of a namespace. The application stays within those limits automatically.
| Item | Value |
|---|---|
| Port | 8080/tcp |
| Volume | /data: SQLite database and JSON copy of the history |
HEALTHCHECK | built in: docker-hub-image-statistics healthcheck (every 30s) |
| Read-only root filesystem | supported (only /data is written) |
| Path | Description |
|---|---|
/ | Web UI |
/api/v1/images, /api/v1/images/{ns}/{name}, .../history?range=24h&step=1h | JSON API |
/api/v1/summary, /api/v1/status, /api/v1/version | Totals, collector status, build info |
/metrics | Prometheus metrics (dockerhub_image_pulls_total, dockerhub_image_pulls{window}, dockerhub_image_pulls_last_collection, ...) |
/healthz, /readyz | Liveness and readiness |
Clone the repository to start the application together with the newest OpenTelemetry Collector, Prometheus, Loki, Tempo, Jaeger and Grafana. They come already wired, with the dashboards provisioned:
git clone https://github.com/aeciopires/docker-hub-image-statistics.git
cd docker-hub-image-statistics
make stack-up
Grafana: http://localhost:3000 · Prometheus: http://localhost:9090 · Jaeger: http://localhost:16686.

git clone https://github.com/aeciopires/docker-hub-image-statistics.git
helm upgrade --install dhis docker-hub-image-statistics/charts/docker-hub-image-statistics \
-n dhis --create-namespace --set 'config.dockerhub.namespaces={myorg}'
helm test dhis -n dhis
The chart includes:
HTTPRoute;extraObjects for any extra manifest;ServiceMonitor and the Grafana dashboards.Details are in the chart README.
gcr.io/distroless/static-debian13:nonroot, pinned by digest: no shell,
no package manager.CGO_ENABLED=0, pure-Go SQLite), runs as UID 65532.--read-only, --cap-drop ALL and no-new-privileges.GPL-3.0. The embedded Roboto font is licensed under the SIL Open Font License 1.1.
Issues and pull requests are welcome. Read the contributing guide, and give the project a ⭐ on GitHub if it helps you.
Content type
Image
Digest
sha256:0e99c840d…
Size
10.1 MB
Last updated
about 17 hours ago
docker pull aeciopires/docker-hub-image-statistics