Understanding and Viewing Docker Hub Pull Rate Limits

| `digest` | The unique image digest for the image. | This helps in identifying the image. | | `version_checks` | The number of version checks accumulated for the date and hour of each image repository. Depending on the client, a pull can do a version check to verify the existence of an image or tag without downloading it. | This helps identify the frequency of version checks, which you can use to analyze usage trends and potential unexpected behaviors. | | `pulls` | The number of pulls accumulated for the date and hour of each image repository. | This helps identify the frequency of repository pulls, which you can use to analyze usage trends and potential unexpected behaviors. | ## View pull rate and limit The pull rate limit is calculated on a 6-hour basis. There is no pull rate limit for users or automated systems with a paid subscription. Unauthenticated and Docker Personal users using Docker Hub will experience rate limits on image pulls. When you issue a pull and you are over the limit, Docker Hub returns a `429` response code with the following body when the manifest is requested: ```text You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits ``` This error message appears in the Docker CLI or in the Docker Engine logs. To view your current pull rate and limit: > [!NOTE] > > To check your limits, you need `curl`, `grep`, and `jq` installed. 1. Get a token. - To get a token anonymously, if you are pulling anonymously: ```console $ TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token) ``` - To get a token with a user account, if you are authenticated, insert your username and password in the following command: ```console $ TOKEN=$(curl --user 'username:password' "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token) ``` 2. Get the headers that contain your limits. These headers are returned on both GET and HEAD requests. Using GET emulates a real pull and counts towards the limit. Using HEAD won't. ```console $ curl --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest ``` 3. Examine the headers. You should see the following headers. ```text ratelimit-limit: 100;w=21600 ratelimit-remaining: 20;w=21600 docker-ratelimit-source: 192.0.2.1 ``` In the previous example, the pull limit is 100 pulls per 21600 seconds (6 hours), and there are 20 pulls remaining. If you don't see any `ratelimit` header, it could be because the image or your IP is unlimited in partnership with a publisher, provider, or an open source organization. It could also mean that the user you are pulling as is part of a paid Docker subscription. Pulling that image won't count toward pull rate limits if you don't see these headers.

This section explains Docker Hub's pull rate limits, which restrict the number of image pulls within a 6-hour window for unauthenticated and Docker Personal users. Paid subscriptions are exempt. The document provides instructions on how to retrieve a token (anonymously or with user credentials) and use it to query the Docker registry to view the current pull rate limit and remaining pulls using `curl`, `grep`, and `jq`. It also describes the HTTP 429 error received when the limit is exceeded and explains scenarios where rate limit headers might not appear.