You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Understanding your Docker Hub usage and rate limits helps you manage your and
8
+
your organization's usage effectively.
8
9
9
-
Docker Hub limits the number of Docker image downloads, or pulls, based on the account type of the user pulling the image. Pull rate limits are based on individual IP address.
10
+
## View Docker Hub usage
10
11
11
-
| User type | Rate limit |
12
-
| --------- | ---------- |
13
-
| Anonymous users | 100 pulls per 6 hours per IP address |
14
-
|[Authenticated users](#how-do-i-authenticate-pull-requests)| 200 pulls per 6 hour period |
15
-
| Users with a paid [Docker subscription](https://www.docker.com/pricing)| Up to 5000 pulls per day |
12
+
You can download a CSV file of your or your organization's Docker Hub usage. To
13
+
download the file:
16
14
17
-
If you require a higher number of pulls, you can also buy an [Enhanced Service Account add-on](service-accounts.md#enhanced-service-account-add-on-pricing).
15
+
1. Sign in to [Docker Hub](https://hub.docker.com).
16
+
17
+
If you want to download usage for all members of an organization, you must
18
+
sign in to an account that is an owner for that organization. Otherwise,
19
+
you can only view your own usage.
20
+
21
+
2. In Docker Hub, navigate to the [**Usage** page](https://hub.docker.com/usage).
22
+
3. In the drop-down, select whether to download your personal data or
23
+
data for an organization.
24
+
4. In **From** and **To**, select a date range for the data.
25
+
5. Select **Send report to email** to have Docker email you a link to the data
26
+
file. Note that email processing time may vary.
18
27
28
+
The file contains the following comma separated values.
|`datehour`| The date and hour (`yyyy/mm/dd/hh`) of the pull that resulted in the data transfer. | This helps in identifying peak usage times and patterns. |
33
+
|`user_name`| The Docker ID of the user that pulled the image | This lets organization owners track data consumption per user and manage resources effectively. |
34
+
|`repository`| The name of the repository of the image that was pulled. | This lets you identify which repositories are most frequently accessed and consume most of the data transfer. |
35
+
|`pat_name`| Name of the personal access token that was used for authentication with Docker CLI. `generated` tokens are automatically generated by the Docker client when a user signs in. | Personal access tokens are usually used to authenticate automated tools (Docker Desktop, CI/CD tools, etc.). This is useful for identifying which automated system issued the pull. |
36
+
|`ips`| The IP address that was used to pull the image. This field is aggregated, so more than one IP address may appear, representing all the IPs used to pull an image within the same date and hour. | This helps you understand the origin of the data transfer, which is useful for diagnosing and identifying patterns in automated or manual pulls. |
37
+
|`repository_privacy`| The privacy state of the image repository that was pulled. This can either be `public` or `private`. | This distinguishes between public and private repositories to identify which data transfer threshold the pull impacts. |
38
+
|`tag`| The tag for the image. The tag is only available if the pull request included a tag. | This helps in identifying the image. Tags are often used to identify specific versions or variants of an image. |
39
+
|`digest`| The unique image digest for the image. | This helps in identifying the image. |
40
+
|`version_checks`| The number of version checks accumulated for the date and hour of each image repository. Depending on the client, a pull request 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. |
41
+
|`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. |
21
42
22
-
A user's limit is equal to the highest entitlement of their
23
-
personal account or any organization they belong to. To take
24
-
advantage of this, you must sign in to
25
-
[Docker Hub](https://hub.docker.com/)
26
-
as an authenticated user. For more information, see
27
-
[How do I authenticate pull requests](#how-do-i-authenticate-pull-requests).
28
-
Unauthenticated (anonymous) users will have the limits enforced via IP.
43
+
## Rate limit
44
+
45
+
A user's rate limit is equal to the highest entitlement of their personal
46
+
account or any organization they belong to. To take advantage of this, you must
47
+
sign in to [Docker Hub](https://hub.docker.com/) as an authenticated user. For
- Pulls are accounted to the user doing the pull, not to the owner of the image.
31
-
- A pull request is defined as up to two `GET` requests on registry
32
-
manifest URLs (`/v2/*/manifests/*`).
33
-
- A normal image pull makes a
34
-
single manifest request.
35
-
- A pull request for a multi-arch image makes two
36
-
manifest requests.
53
+
- A pull request is defined as up to two `GET` requests on registry manifest
54
+
URLs (`/v2/*/manifests/*`).
55
+
- A normal image pull makes a single manifest request.
56
+
- A pull request for a multi-arch image makes two manifest requests.
37
57
-`HEAD` requests aren't counted.
38
-
- Some images are unlimited through our [Docker Sponsored Open Source](https://www.docker.com/blog/expanded-support-for-open-source-software-projects/) and [Docker Verified Publisher](https://www.docker.com/partners/programs) programs.
58
+
- Some images are unlimited through the [Docker Sponsored Open
| Anonymous users | 100 pulls per 6 hours per IP address |
72
+
|[Authenticated users](#how-do-i-authenticate-pull-requests)| 200 pulls per 6 hour period |
73
+
| Users with a paid [Docker subscription](https://www.docker.com/pricing)| Up to 5000 pulls per day |
41
74
42
-
When you issue a pull request and you are over the limit, Docker Hub returns a `429` response code with the following body when the manifest is requested:
75
+
If you require a higher number of pulls, you can also buy an [Enhanced Service Account add-on](service-accounts.md#enhanced-service-account-add-on-pricing).
76
+
77
+
### How do I know my pull requests are being limited?
78
+
79
+
When you issue a pull request and you are over the limit, Docker Hub returns a
80
+
`429` response code with the following body when the manifest is requested:
43
81
44
82
```text
45
83
You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits
46
84
```
47
85
48
86
This error message appears in the Docker CLI or in the Docker Engine logs.
49
87
50
-
## How can I check my current rate?
88
+
###How can I check my current rate?
51
89
52
-
Valid API requests to Hub usually include the following rate limit headers in the response:
90
+
Valid API requests to Hub usually include the following rate limit headers in
91
+
the response:
53
92
54
93
```text
55
-
ratelimit-limit
94
+
ratelimit-limit
56
95
ratelimit-remaining
57
96
docker-ratelimit-source
58
97
```
@@ -61,15 +100,17 @@ These headers are returned on both GET and HEAD requests.
61
100
62
101
>**Note**
63
102
>
64
-
>Using GET emulates a real pull and counts towards the limit. Using HEAD won't. To check your limits, you need `curl`, `grep`, and `jq` installed.
103
+
> Using GET emulates a real pull and counts towards the limit. Using HEAD won't.
104
+
> To check your limits, you need `curl`, `grep`, and `jq` installed.
65
105
66
106
To get a token anonymously, if you are pulling anonymously:
### I'm being limited to a lower rate even though I have a paid Docker subscription
93
147
94
-
### I don't see any RateLimit headers
148
+
To take advantage of the higher limits included in a paid Docker subscription,
149
+
you must [authenticate pulls](#how-do-i-authenticate-pull-requests) with your
150
+
user account.
95
151
96
-
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 plan. Pulling that image won’t count toward pull limits if you don’t see these headers. However, users with a paid Docker subscription pulling more than 5000 times daily require a [Service Account](../docker-hub/service-accounts.md) subscription.
152
+
A Pro, Team, or a Business tier doesn't increase limits on your images for other
##I'm being limited to a lower rate even though I have a paid Docker subscription
158
+
### Other limits
99
159
100
-
To take advantage of the higher limits included in a paid Docker subscription, you must [authenticate pulls](#how-do-i-authenticate-pull-requests) with your user account.
160
+
Docker Hub also has an overall rate limit to protect the application and
161
+
infrastructure. This limit applies to all requests to Hub properties including
162
+
web pages, APIs, and image pulls. The limit is applied per-IP, and while the
163
+
limit changes over time depending on load and other factors, it's in the order
164
+
of thousands of requests per minute. The overall rate limit applies to all users
165
+
equally regardless of account level.
101
166
102
-
A Pro, Team, or a Business tier doesn't increase limits on your images for other users. See Docker's [Open Source](https://www.docker.com/blog/expanded-support-for-open-source-software-projects/), [Publisher](https://www.docker.com/partners/programs), or [Large Organization](https://www.docker.com/pricing) offerings.
167
+
You can differentiate between these limits by looking at the error code. The
168
+
"overall limit" returns a simple `429 Too Many Requests` response. The pull
169
+
limit returns a longer error message that includes a link to this page.
103
170
104
171
## How do I authenticate pull requests?
105
172
106
-
The following section contains information on how to sign in to Docker Hub to authenticate pull requests.
173
+
The following section contains information on how to sign in to Docker Hub to
174
+
authenticate pull requests.
107
175
108
176
### Docker Desktop
109
177
110
-
If you are using Docker Desktop, you can sign in to Docker Hub from the Docker Desktop menu.
178
+
If you are using Docker Desktop, you can sign in to Docker Hub from the Docker
179
+
Desktop menu.
111
180
112
-
Select **Sign in / Create Docker ID** from the Docker Desktop menu and follow the on-screen instructions to complete the sign-in process.
181
+
Select **Sign in / Create Docker ID** from the Docker Desktop menu and follow
182
+
the on-screen instructions to complete the sign-in process.
113
183
114
184
### Docker Engine
115
185
116
-
If you're using a standalone version of Docker Engine, run the `docker login` command from a terminal to authenticate with Docker Hub. For information on how to use the command, see [docker login](../reference/cli/docker/login.md).
186
+
If you're using a standalone version of Docker Engine, run the `docker login`
187
+
command from a terminal to authenticate with Docker Hub. For information on how
188
+
to use the command, see [docker login](../reference/cli/docker/login.md).
117
189
118
190
### Docker Swarm
119
191
120
-
If you're running Docker Swarm, you must use the `-- with-registry-auth` flag to authenticate with Docker Hub. For more information, see [Create a service](../reference/cli/docker/service/create.md/#create-a-service). If you are using a Docker Compose file to deploy an application stack, see [docker stack deploy](../reference/cli/docker/stack/deploy.md).
192
+
If you're running Docker Swarm, you must use the `--with-registry-auth` flag to
193
+
authenticate with Docker Hub. For more information, see [Create a
194
+
service](../reference/cli/docker/service/create.md#with-registry-auth). If you
195
+
are using a Docker Compose file to deploy an application stack, see [docker
If you're using GitHub Actions to build and push Docker images to Docker Hub, see [login action](https://github.com/docker/login-action#dockerhub). If you are using another Action, you must add your username and access token in a similar way for authentication.
200
+
If you're using GitHub Actions to build and push Docker images to Docker Hub,
201
+
see [login action](https://github.com/docker/login-action#dockerhub). If you are
202
+
using another Action, you must add your username and access token in a similar
203
+
way for authentication.
125
204
126
205
### Kubernetes
127
206
128
-
If you're running Kubernetes, follow the instructions in [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) for information on authentication.
207
+
If you're running Kubernetes, follow the instructions in [Pull an Image from a
0 commit comments