Docker Hub usage and rate limits

Table of contents

Docker may impose usage and rate limits for Docker Hub to ensure fair resource consumption and maintain service quality. Understanding your usage helps you manage your and your organization's usage effectively.

Usage

Usage refers to both:

Pulls: The amount of data transferred from Docker Hub
Storage: The amount of data stored on Docker Hub

Fair use

When utilizing the Docker Platform, users should be aware that excessive data transfer, pull rates, or data storage can lead to throttling, or additional charges. To ensure fair resource usage and maintain service quality, we reserve the right to impose restrictions or apply additional charges to accounts exhibiting excessive data and storage consumption.

View Docker Hub usage

Sign in to Docker Hub.
If you want to download usage for all members of an organization, you must sign in to an account that is an owner for that organization. Otherwise, you can only view your own personal usage.
In Docker Hub, select Usage from the top-level navigation menu.
In the drop-down, select whether you want to view your personal or organization data.
The usage page displays Pulls and Storage usage.
Select a usage type and use the available filters to view usage.

Download Docker Hub pulls usage

You can download a CSV file of your or your organization's Docker Hub pulls usage. You can't download a CSV file for storage usage.

To download the pulls usage file:

Sign in to Docker Hub.
If you want to download usage for all members of an organization, you must sign in to an account that is an owner for that organization. Otherwise, you can only view your own personal usage.
In Docker Hub, select Usage from the top-level navigation menu.
In the drop-down, select whether you want to view your personal or organization data.
Optional. Use the Filter by privacy drop-down to select Public or Private pulls.
Use the From and To filters to select a date range for the data.
Select Send report to email to have Docker email you a link to the data file. Note that email processing time may vary.

The file contains the following comma separated values:

CSV column	Definition	Usage guidance
`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.
`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.
`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.
`access_token_name`	Name of the 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.
`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.
`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.
`tag`	The tag for the image. The tag is only available if the pull included a tag.	This helps in identifying the image. Tags are often used to identify specific versions or variants of an image.
`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.

Best practices for managing Docker Hub usage

Use the following steps to help optimize and manage your Docker Hub usage for both individuals and organizations:

View your Docker Hub usage.
Use the Docker Hub usage data to identify which accounts consume the most data, determine peak usage times, and identify which images are related to the most data usage. In addition, look for usage trends, such as the following:
- Inefficient pull behavior: Identify frequently accessed repositories to assess whether you can optimize caching practices or consolidate usage to reduce pulls.
- Inefficient automated systems: Check which automated tools, such as CI/CD pipelines, may be causing higher pull rates, and configure them to avoid unnecessary image pulls.
Optimize image pulls by:
- Use caching: Implement local image caching via mirroring or within your CI/CD pipelines to reduce redundant pulls.
- Automate manual workflows: Avoid unnecessary pulls by configuring automated systems to pull only when a new version of an image is available.
Optimize your storage by:
- Regularly audit and remove repositories with untagged, unused, or outdated images.
- Look for private repositories in Hub storage that exceed your plan's limits.
Increase your limits by upgrading or purchasing additional consumption. For details, see Scale your subscription.
For organizations, monitor and enforce organizational policies by doing the following:
- Routinely view Docker Hub usage to monitor usage.
- Enforce sign-in to ensure that you can monitor the usage of your users and users receive higher usage limits.
- Look for duplicate user accounts in Docker and remove accounts from your organization as needed.

Storage and repository limits

Note
The Docker Hub plan limits will take effect on March 1, 2025. No charges on Docker Hub image pulls or storage will be incurred between December 10, 2024, and February 28, 2025.

The following storage and repository limits apply based on your subscription, subject to fair use:

Plan	Public repositories	Public repository storage	Private repositories	Private repository storage
Personal	Unlimited	Unlimited	Up to 1 private repository	Up to 2 GB
Pro	Unlimited	Unlimited	Unlimited	Up to 5 GB
Team	Unlimited	Unlimited	Unlimited	Up to 50 GB
Business	Unlimited	Unlimited	Unlimited	Up to 500 GB

Private repository storage is calculated on a monthly basis based on the average storage used throughout the month per organization. Docker measures your storage usage in the amount of Bytes stored per hour, which are accumulated throughout the month to determine your monthly storage. If a repository is private at any point within an hour, it is counted as private for the full hour. The total hours are calculated based on the actual number of days in the month. Any storage usage beyond the included amounts in each paid subscription tier will be charged at an on-demand rate. You can scale your limit or upgrade to get a higher limit.

For more information on how Docker Hub storage pricing is calculated, see the Docker Hub storage pricing guide.

Pull limit and rate limit

A pull is defined as the following:

A Docker pull includes both a version check and any download that occurs as a result of the pull. Depending on the client, a docker pull can verify the existence of an image or tag without downloading it by performing a version check.
Version checks do not count towards usage pricing.
A pull for a normal image makes one pull for a single manifest.
A pull for a multi-arch image will count as one pull for each different architecture.

Pull attribution

Pulls can be attributed to either a personal or organization namespace.

Private pulls

Pulls for private repositories are attributed to the repository's namespace owner.

Public pulls

When pulling images from a public repository, attribution is determined based on domain affiliation and organization membership.

Verified domain ownership

When pulling an image from an account linked to a verified domain, the attribution is set to be the owner of that domain

Single organization membership

If the owner of the verified domain is a company and the user is part of only one organization within that company, the pull is attributed to that specific organization.
If the user is part of only one organization, the pull is attributed to that specific organization.

Multiple organization memberships

If the user is part of multiple organizations under the company, the pull is attributed to the user's personal namespace.

Pull limit

Rate limits apply to pull usage. A user's rate limit is equal to the highest entitlement of their personal account or any organization they belong to. To take advantage of this, you must sign in to Docker Hub as an authenticated user. For more information, see How do I authenticate pull requests. Unauthenticated (anonymous) users will have the limits enforced via IP.

Pull limit refers to the total number of image pulls allowed within a specific time frame. For example, a Business plan has a total pull limit of 1M pulls per month.

The pull limit is calculated on a per month basis and only applies to Docker Pro, Docker Team, and Docker Business users. The limit automatically scales on-demand, but on-demand rates do apply. You can scale your limit or upgrade to get a higher limit.

User type	Pull count per month
Business (authenticated)	1M
Team (authenticated)	100K
Pro (authenticated)	25K
Personal (authenticated)	Not applicable
Unauthenticated users	Not applicable

Pull rate limit

Pull rate limit refers to the frequency of image pulls per unit of time, specifying how quickly you can pull images within a specific time.

The pull rate limit is calculated on a per 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.

The following table describes the pull rate limit per hour for each subscription tier, subject to fair use:

User type	Pull rate limit per hour
Business (authenticated)	No limit
Team (authenticated)	No limit
Pro (authenticated)	No limit
Personal (authenticated)	40
Unauthenticated users	10 per IP address

Tip
Always sign in to Docker. Authenticated Docker Personal users receive increased rate limits, while authenticated Docker Pro, Team, and Business users are not rate limited. For more information, see How do I authenticate pulls.

How do I know my pulls are being limited?

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:

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.

How can I check my current rate?

Valid API requests to Hub usually include the following rate limit headers in the response:

ratelimit-limit
ratelimit-remaining
docker-ratelimit-source

These headers are returned on both GET and HEAD requests.

Note
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.

To get a token anonymously, if you are pulling anonymously:

$ 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):

$ TOKEN=$(curl --user 'username:password' "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)

Then to get the headers showing your limits, run the following:

$ curl --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest

Which should return the following headers:

ratelimit-limit: 100;w=21600
ratelimit-remaining: 76;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 76 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 plan. Pulling that image won’t count toward pull rate limits if you don't see these headers. Note that users with a paid subscription have a monthly pull limit that can be viewed in the Docker Hub usage dashboard.

I'm being limited to a lower rate even though I have a paid Docker subscription

To take advantage of the unlimited limits included in a paid Docker subscription, you must authenticate pulls with your user account.

A Pro, Team, or a Business tier doesn't increase limits on your images for other users. See Docker's Open Source, Publisher, or Large Organization offerings.

Other limits

Docker Hub also has an abuse rate limit to protect the application and infrastructure. This limit applies to all requests to Hub properties including web pages, APIs, and image pulls. The limit is applied per-IP, and while the limit changes over time depending on load and other factors, it's in the order of thousands of requests per minute. The abuse limit applies to all users equally regardless of account level.

You can differentiate between these limits by looking at the error code. The "abuse limit" returns a simple 429 Too Many Requests response. The pull limit returns a longer error message that includes a link to this page.