---
updatedAt: 2026-09-21T11:11:41.000Z
agentTools:
siteIndex: https://docs.jfrog.com/llms.txt
projectIndex: https://docs.jfrog.com/artifactory/llms.txt
---
# Docker Repositories
Connect your Docker client to JFrog Artifactory using docker login or manual credentials so you can push and pull images from private Docker repositories.
Docker is a platform that lets you develop, ship, and run applications in environments called containers. Containers allow you to run applications consistently with all dependencies across different environments. Integrating Docker with JFrog Artifactory provides a secure, private, and powerful registry for your Docker images, giving you fine-grained control over your development and distribution pipeline. For more information, see the Docker documentation.
**Note**
Both Artifactory and Docker use the term "repository", but each uses it in a different way:
* **Docker repository**:Â A hosted collection of tagged images that creates the file system for a container.
* **Docker registry**:Â A host that stores Docker repositories.
* **Artifactory repository**: A hosted collection of Docker repositories, effectively a Docker registry that you can access transparently with the Docker client. An Artifactory repository for Docker images is also called a "Docker repository" in Artifactory documentation.
Artifactory does not limit the number of repositories you can create, so you can manage any number of Docker registries in Artifactory.
Using Artifactory as your Docker registry provides the following benefits:
* **Secure and Private Registries**: Host your Docker images in a secure environment with granular access control.
* **Support for Docker Registry API**: Artifactory supports the relevant Docker Registry APIÂ calls so that you can use the Docker client natively to access images through Artifactory.
* **Unlimited Docker Hub Access**: Artifactory provides SaaS users with unlimited, high-performance, unauthenticated access to Docker Hub. To avoid usage-based rate limits and to pull images from private repositories, authentication is recommended.
* **OCI Support:** Artifactory is OCI-compliant and supports OCI clients, enabling you to deploy and resolve OCI images in Docker registries.
* **Local, Remote, and Virtual Repositories**: Manage internal images, proxy public images from Docker Hub, and aggregate multiple registries under a single URL.
* **CI/CD Integration**: Seamlessly integrate with your continuous integration and delivery pipelines for automated builds, testing, and deployment.
* **High Availability and Redundancy**: Ensure reliable access to your Docker images with Artifactory's support for high-availability configurations.
## Get Started with Docker
To get started working with Docker, complete the following main steps:
1. Create a Docker Repository
2. Connect your Docker Client to Artifactory
3. Publish and install OCI images using a supported client:
* Docker CLI
* Podman
# Create a Docker Repository
This topic describes how to create a Docker Repository. This is required before pushing and pulling Docker images. There are three primary types of repositories:
* **Local repositories**: Store and share first- and second-party packages with your organization
* **Remote repositories**: Download from any remote location, including external package registries or other Artifactory instances
* **Virtual repositories**: Aggregate remote and local repositories, enabling your organization to scale by providing a single URL to access multiple repositories and package types
For more information about JFrog repositories, see [Repository Management](https://docs.jfrog.com/artifactory/docs/repository-management).
**Prerequisite**: You need Admin or Project Admin permissions to create a Docker repository. If you don't have Admin permissions, the option will not be available.
**To create a Docker repository**:
1. In the **Administration** tab, click **Repositories** > **Create a Repository**.
2. Select the type of repository you want to create: **Local**, **Remote**, or **Virtual**.
3. Select the **Docker** package type.
4. Configure the required fields for the repository:
**Note**
Do not use underscores in the repository name. Due to subdomain/DNS/hostname limitations, Docker cannot communicate with registries that have underscores in the name.
For example, do not use the name `docker_dev_local`. Instead, use `docker-dev-local` or `docker.dev.local`.
* For local repositories:
* In the **Repository Key** field, type a meaningful name for the repository. For example, `docker-dev-local`.
* In the **Docker Settings** section, set the API version to **V2**.
* Set the **Max Unique Tags** and **Docker Tag Retention** values. For more information, see [Tag Retention Logic](/docs/additional-docker-information#tag-retention-logic).
For more information on local repositories and all its possible settings, see [Local Repositories](https://docs.jfrog.com/artifactory/docs/local-repositories).
* For remote repositories, additionally verify the **Repository URL** and update it if needed.
Artifactory provides Cloud users with unlimited, high-performance, unauthenticated access to Docker Hub at `https://registry-1.docker.io/`. To avoid rate limits and to pull images from private repositories, authenticate your Docker Hub connection by entering your credentials in the **User Name** and **Password/Access Token** fields. Self-Hosted deployments of Artifactory are subject to rate limits.
For more information on Remote Repositories and all its possible settings, see [Remote Repositories](https://docs.jfrog.com/artifactory/docs/remote-repositories).
* For virtual repositories, additionally select one or more local or remote Docker repositories to include in the virtual repository. Optionally, set a default deployment repository. For more information on virtual repositories and all its possible settings, see [Virtual Repositories](https://docs.jfrog.com/artifactory/docs/virtual-repositories).
To learn how to configure virtual Docker repositories to pull images based on modification time, see [Resolve Latest Docker Image](/docs/additional-docker-information#resolve-latest-docker-image).
5. Click **Create Repository**.
The repository is created and the Repositories window is displayed.
## Repository Metadata and Permissions
Any user with read access to a repository can view its metadata, which includes the list of package, image, or artifact names it holds. This includes users whose access is scoped to a specific path.
Access to package content is governed separately by your permission targets. Users see the names of packages in repositories they can read, and download the packages their permissions allow.
**Tip**
To isolate metadata visibility between teams, assign each team its own local repository, then aggregate them behind a virtual repository. Developers resolve through a single URL, and each team only sees the metadata of the repositories they can read.
# Connect your Docker Client to Artifactory
This section provides details on configuring Docker to work with Artifactory.
**Prerequisite**: Before connecting your Docker client to Artifactory, you must have an existing Docker repository in Artifactory. For more information, see Create a Docker Repository.
**Note**
Depending on your hosting framework, the URL for your Docker repository may vary. For examples of different URL formats by hosting framework and method, see [Docker Repository URL Formats](/docs/additional-docker-information#docker-repository-url-formats).
**To connect your Docker client to Artifactory:**
Follow the instructions for one of the supported clients:
* Docker CLI
* Podman
## Docker CLI
The following topics describe how to configure and use the Docker CLI with Artifactory:
* Connect Docker CLI to Artifactory
* [Push Docker Images with Docker CLI](#push-docker-images-with-docker-cli)
* Pull Docker Images with Docker CLI
### Connect Docker CLI to Artifactory
You can configure the Docker CLI to work with Artifactory using two methods.
**To connect Docker CLI to Artifactory:**
* [`docker login`](/docs/docker-repositories#connect-docker-to-artifactory-using-docker-login)
* [Set credentials manually](#connect-docker-to-artifactory-by-manually-setting-credentials)
**Logged-In and Anonymous Users:** You can work with Docker and Artifactory as either a logged-in user or as an anonymous user without logging in. To work with Artifactory using Anonymous Access, configure that access under **Administration** > **Security** > **General**. For more information, see Allow Anonymous Access.
#### Connect Docker to Artifactory using `docker login`
**To connect Docker to Artifactory using `docker login`:**
* Run the following command:
```shell
docker login
```
Where:
* ``: The URL of your JPD, without the protocol schema
For example:
```shell
docker login company.jfrog.io
```
**Note**
You can also use JFrog Set Me Up to copy the snippet populated with your token and environment. For more information, see [Use Artifactory Set Me Up for Configuring Package Manager Clients](/artifactory/docs/use-artifactory-set-me-up-for-configuring-package-manager-clients).
#### Connect Docker to Artifactory by Manually Setting Credentials
You can manually set your Docker credentials to authenticate in automated workflows, or if you are using Docker V1. For more information, see [Use Docker V1](/docs/additional-docker-information#use-docker-v1).
You can copy your authentication snippet from Set Me Up, or you can retrieve credentials directly from Artifactory by running this command:
```shell
curl -u: "https:///artifactory/api/docker///auth"
```
Where:
* ``: Your Artifactory username
* ``: Your Artifactory password
* ``: The URL of your JPD
* ``: The name of the target repository
* ``: The version of Docker you are using, either `V1` or `V2`.
**To manually set Docker credentials:**
* Add the following snippet to your `~/.docker/config.json` file:
```json
{
"auths": {
"https://" : {
"auth": "",
"email": ""
}
}
}
```
Where:
* **``**: The URL of your JFrog Platform
* **``**: Your Base64-encoded Artifactory username and password
* **``**: The email address associated with your Artifactory account
For example:
```json
{
"auths": {
"https://company.jfrog.io" : {
"auth": "YWRtaW46QVA1N05OaHZTMnM5Qk02RkR5RjNBVmF4TVFl",
"email": "jeffry@frog.com"
}
}
}
```
**Note**
You can also use JFrog Set Me Up to copy the snippet populated with your token and environment. For more information, see [Use Artifactory Set Me Up for Configuring Package Manager Clients](/artifactory/docs/use-artifactory-set-me-up-for-configuring-package-manager-clients).
**Next steps:**
* Pull Docker Images with Docker CLI
* Push Docker Images with Docker CLI
### Push Docker Images with Docker CLI
You can use Docker commands to push multiple kinds of images to Artifactory:
* Push Single-Architecture Images with Docker CLI
* Push Multi-Architecture Images with Docker CLI
Starting from Artifactory 7.21.2, you can also push multi-architecture images with Docker BuildX. For more information, see [Push Multi-Architecture Docker Images with BuildX](#push-multi-architecture-docker-images-with-buildx).
#### Push Single-Architecture Images with Docker CLI
1. Tag your image by running the following command:
```shell
docker tag [JFrogPlatformURL]//:
```
Where:
* ``: The existing image ID
* `[JFrogPlatformURL]`: The URL of your JPD, without the protocol schema
* ``: The name of the target repository
* ``: The image name
* ``: The tags you want to apply to the image
For example:
```shell
docker tag a1b2c3d4e5f6 company.jfrog.io/docker-local/froggy-app:v1.0.0
```
2. Run the following command to push the image to Artifactory:
```shell
docker push [JFrogPlatformURL]//:
```
Where:
* `[JFrogPlatformURL]`: The URL of your JPD, without the protocol schema
* ``: The name of the target repository
* ``: The image name
* ``: The tags you want to apply to the image
For example:
```shell
docker push company.jfrog.io/docker-local/froggy-app:v1.0.0
```
**Note**
You can also use JFrog Set me up to copy the snippet populated with your token and environment. For more information, see Use Artifactory Set Me Up for Configuring Package Manager Clients.
#### Push Multi-Architecture Images with Docker CLI
You can push multi-architecture Docker images, using a manifest list file, or fat manifest, which references image manifests for platform-specific versions of an image.
Starting from Artifactory 7.21.2, you can also push multi-architecture images with Docker BuildX. For more information, see Push Multi-Architecture Docker Images with BuildX.
1. For each architecture you want to include in the final multiple-architecture image, build the image by running this command:
```shell
docker build -t [JFrogPlatformURL]//: --build-arg ARCH=
```
Where:
* `[JFrogPlatformURL]`: The URL of your JPD, without the protocol schema
* ``: The name of the repository where the image is located
* ``: The image name
* ``: The tags you want to apply to the image
* ``: The architecture you want to build for
* ``: The path to the Docker file
For example:
```shell
docker build -t company.jfrog.io/docker-local/froggy-app:v1.0.0 --build-arg ARCH=amd64 .
```
2. For each image you built, push it to Artifactory by running this command:
```shell
docker push [JFrogPlatformURL]//:
```
Where:
* `[JFrogPlatformURL]`: The URL of your JPD, without the protocol schema
* ``: The name of the target repository
* ``: The image name
* ``: The tags you want to apply to the image
For example:
```shell
docker push company.jfrog.io/docker-local/froggy-app:v1.0.0
```
3. Run the following command to create a local manifest file, referencing all the platform-specific images you just built:
```shell
docker manifest create \
[JFrogPlatformURL]//: \
--amend [JFrogPlatformURL]//: \
--amend [JFrogPlatformURL]//:
```
Where:
* `[JFrogPlatformURL]`: The URL of your JPD, without the protocol schema
* ``: The name of the target repository
* ``: The name of the multiple architecture image you want to build
* ``: The tags you want to apply to the image
* ``: The name of the platform-specific image you built
**Note**
Add a new `--amend` for each image you want to include in the multi-architecture image.
For example:
```shell
docker manifest create \
company.jfrog.io/docker-local/multiarch-image:latest \
--amend company.jfrog.io/docker-local/froggy-app:v1.0.0 \
--amend company.jfrog.io/docker-local/swamp-app:v2.2.1
```
4. Run the following command:
```shell
docker manifest push [JFrogPlatformURL]//:
```
Where:
* `[JFrogPlatformURL]`: The URL of your JPD, without the protocol schema
* ``: The name of the target repository
* ``: The multi-architecture image name
* ``: The tags you want to apply to the image
For example:
```shell
docker manifest push company.jfrog.io/docker-local/multiarch-image:latest
```
**Multi-Architecture Tagging**
Starting from Artifactory version 7.21.2, when you push a platform-specific Docker image, the server automatically adds a second descriptive tag that includes the operating system.
For example, when you push `my-app:1.0-amd64`, Artifactory publishes `my-app:1.0-linux-amd64`.
#### Push Multi-Architecture Docker Images with BuildX
Docker Buildx is a plugin for the Docker CLI that extends the core `docker build` command with advanced features powered by Moby BuildKit. You can use BuildX to easily build and push multi-architecture images with a single command.
**To build and push multi-architecture images with BuildX:**
1. Run this command to open a new builder instance that you can use to build images for multiple architectures:
```shell
docker buildx create --use
```
2. Build and publish multiple images by running the following command:
```shell
docker buildx build --platform -t [JFrogPlatformURL]//: . --push
```
Where:
* ``: A comma-separated list of the operating system and CPU combinations you want to build
* `[JFrogPlatformURL]`: The URL of your JPD, without the protocol schema
* ``: The repository where the image is located
* ``: The image name
* ``: The tags identifying the version of the image you want to pull
For example:
```shell
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7,linux/s390x,linux/ppc64le -t company.jfrog.io/docker-local/froggy-app:v1.0.0 . --push
```
### Pull Docker Images with Docker CLI
Run the following command:
```shell
docker pull [JFrogPlatformURL]//:
```
Where:
* `[JFrogPlatformURL]`: The URL of your JPD, without the protocol schema
* ``: The repository where the image is located
* ``: The image name
* ``: The tags identifying the version of the image you want to pull
For example:
```shell
docker pull company.jfrog.io/docker-local/froggy-app:v1.0.0
```
**Note**
You can also use JFrog Set me up to copy the snippet populated with your token and environment. For more information, see Use Artifactory Set Me Up for Configuring Package Manager Clients.
## Podman
The following topics describe how to configure and use Podman with Artifactory:
* Connect Podman to Artifactory
* [Push Docker Images with Podman](#push-docker-images-with-podman)
* [Pull Docker Images with Podman](#pull-docker-images-with-podman)
### Connect Podman to Artifactory
Podman, or the Pod Manager, is a tool for managing, developing, and running OCI images on Linux systems. It is daemonless, which makes it more accessible and less vulnerable to security breaches than other clients. You can configure Podman to work with Artifactory using two methods:
* [`podman login`](#connect-podman-to-artifactory-using-podman-login)
* [Set credentials manually](/docs/oci-repositories)
**Logged in vs. Anonymous User**: You can work with Podman and Artifactory as either a logged-in user, or as an anonymous user without logging in. To work with Artifactory using Anonymous Access, configure that access under **Admin > Security > General**. For details, refer to Allow Anonymous Access.
#### Connect Podman to Artifactory Using `podman login`
1. Run the following command:
```shell
podman login [JFrogPlatformURL]
```
Where:
* `[JFrogPlatformURL]`: The URL of your JPD, without the protocol schema
For example:
```shell
podman login company.jfrog.io
```
2. Enter your Artifactory credentials.
**Note**
You can also use JFrog Set me up to copy the snippet populated with your token and environment. For more information, see Use Artifactory Set Me Up for Configuring Package Manager Clients.
#### Connect Podman to Artifactory Manually
By default, Podman looks for authentication information in `${XDG_RUNTIME_DIR}/containers/auth.json`. If no valid credentials are found in the file, Podman falls back to the `~/.docker/config.json` file. You can also specify a different authentication file path by using the `--authfile` flag with your Podman commands.
**To manually connect Podman to Artifactory:**
Add the following snippet to the `${XDG_RUNTIME_DIR}/containers/auth.json` or `~/.docker/config.json` file:
```
{
"auths": {
"[JFrogPlatformURL]" : {
"auth": "",
"email": ""
}
}
}
```
Where:
* `[JFrogPlatformURL]`: The URL of your JPD, without the protocol schema
* ``: Your Base64-encoded credentials
* ``: The email address you use to access your JFrog account
For example:
```
{
"auths": {
"company.jfrog.io" : {
"auth": "ZGVtb191c2VyOnNhbXBsZV9hdXRoX3Rva2VuXzEyMzQ1QUJDREVGRg==",
"email": "jeffry@frog.com"
}
}
}
```
**Note**
You can also use JFrog Set me up to copy the snippet populated with your token and environment. For more information, see Use Artifactory Set Me Up for Configuring Package Manager Clients.
**Next steps:**
* Push Docker Images with Podman
* [Pull Docker Images with Podman](#pull-docker-images-with-podman)
### Push Docker Images with Podman
**To tag and push Docker images with Podman:**
1. Tag your image by running the following command:
```shell
podman tag [JFrogPlatformURL]//:
```
Where:
* ``: The existing image ID
* `[JFrogPlatformURL]`: The URL of your JPD, without the protocol schema
* ``: The name of the repository where the image is located
* ``: The image name
* ``: The tags you want to apply to the image
For example:
```shell
podman tag a1b2c3d4e5f6 company.jfrog.io/docker-local/froggy-app:v1.0.0
```
2. Run the following command to push the image to Artifactory:
```shell
podman push [JFrogPlatformURL]//:
```
Where:
* `[JFrogPlatformURL]`: The URL of your JPD, without the protocol schema
* ``: The name of the target repository
* ``: The image name
* ``: The tags you want to apply to the image
**Tip**
Optionally, you can add the`-f=oci` flag to set the image format to OCI.
For example:
```shell
podman push [JFrogPlatformURL]/docker-local/froggy-app:v1.0.0 -f=oci
```
### Pull Docker Images with Podman
Run the following command:
```shell
podman pull [JFrogPlatformURL]//:
```
Where:
* `[JFrogPlatformURL]`: The URL of your JPD, without the protocol schema
* ``: The repository where the image is located
* ``: The image name
* ``: The tags identifying the version of the image you want to pull
For example:
```shell
podman pull company.jfrog.io/docker-local/froggy-app:v1.0.0
```
**Note**
You can also use JFrog Set me up to copy the snippet populated with your token and environment. For more information, see Use Artifactory Set Me Up for Configuring Package Manager Clients.
# Docker Limitations in Artifactory
The following are the limitations of Docker in Artifactory:
* **Key length limits**: Key length limitations exist for Docker OCI and Helm OCI repositories to ensure proper operation and accessibility of repositories using the Docker subdomain method on SaaS platforms:
* **Hard limit**:Â The maximum allowable length for repository keys is 63 characters. This limit is enforced strictly and cannot be exceeded.
* **Soft limit**:Â The soft limit is 63 minus the sum of the server name length and 1. This means the effective length for the repository key may be shorter, depending on the combined length of the server name. For example, if the server name is `myserver`, its length is 8 characters. The soft limit is 63 characters minus the sum of 8 and 1, which is 54.
You will receive a warning when creating a repository or after creating a repository via API. You can create the repository, but no DNS record will be created, making the repository inaccessible unless you manage DNS records internally.
If you are migrating from a self-hosted environment to SaaS, existing repositories with keys equal to or exceeding 63 characters may cause access issues.
* **Docker client limitations**:
* You cannot use a context path when providing the registry path, for example `localhost:8082/artifactory`Â is invalid
* Docker will only send basic HTTP authentication when working against an HTTPS host or when using the insecure registry flag
Artifactory offers solutions to these limitations with reverse proxies for self-hosted deployments and out-of-the-box support for Docker repositories in SaaS environments.
* **Smart Remote property synchronization**: Docker Smart Remote repositories don't synchronize properties for pulls resolved by digest paths such as `sha256__`. For more information, see [Synchronized Properties](/docs/smart-remote-repositories#synchronized-properties).