---
title: "Run Docker commands"
description: "Build Docker images and run Docker commands within the Docker execution environment using remote Docker and the setup_remote_docker key."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-26"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# Run Docker commands

Use the remote Docker environment to build Docker images within the Docker execution environment.

When you use remote Docker for a job, all Docker commands execute locally on the virtual machine used to spin up your primary Docker container.

The _remote_ in "remote Docker" is a legacy term from when remote Docker usage would spin up a separate, remote environment for running Docker commands.

## Introduction

To build Docker images (for example, using `docker` or `docker compose` commands) when using the Docker execution environment, you must use the `setup_remote_docker` key in your job:

**Using Docker?** Authenticating Docker pulls from image registries is recommended when using the Docker execution environment. Authenticated pulls allow access to private Docker images, and may also grant higher rate limits, depending on your registry provider. For further information, see [Using Docker Authenticated Pulls](https://circleci.com/docs/guides/execute/private-images/).

```yaml
jobs:
  build:
    docker:
      - image: cimg/base:2022.06
    steps:
      # ... steps for building/testing app ...
      - setup_remote_docker
```

Using `setup_remote_docker` for a job means that all Docker commands execute locally on the same virtual machine that spins up the primary container.

In the CircleCI web app, jobs that run in the remote Docker environment have the **Remote Docker** label, as follows:

> **Image:** Remote Docker label

Figure 1. Remote Docker label

Only use `setup_remote_docker` key for jobs where your primary executor _is_ a Docker container. If your job uses a VM rather than a container (for example, your executor is `machine`) you do **not** need to use the `setup_remote_docker` key. For an example, see [Run Docker commands using the `machine` executor](#run-docker-commands-using-the-machine-executor).

## Specifications

Contact your system administrator for the remote Docker specifications for your installation.

## Run Docker commands using the Docker executor

The example below shows how you can build and deploy a Docker image for our [demo Docker project](https://github.com/CircleCI-Public/circleci-demo-docker) using the Docker executor, with remote Docker:

```yml
version: 2.1

jobs:
  build:
    docker:
      - image: cimg/go:1.17
    resource_class: xlarge
    steps:
      - checkout
      # ... steps for building/testing app ...

      - setup_remote_docker:
          docker_layer_caching: true

      # build and push Docker image
      - run: |
          TAG=0.1.$CIRCLE_BUILD_NUM
          docker build -t CircleCI-Public/circleci-demo-docker:$TAG .
          echo $DOCKER_PASS | docker login -u $DOCKER_USER --password-stdin
          docker push CircleCI-Public/circleci-demo-docker:$TAG
```

Below is a breakdown of what is happening during this build’s execution:

*   All commands execute in the [Primary Container](https://circleci.com/docs/reference/glossary/#primary-container). (line 5).
    
*   Once you call `setup_remote_docker`, all Docker-related commands execute locally. (line 12).
    
*   Enable [Docker Layer Caching](https://circleci.com/docs/reference/glossary/#docker-layer-caching) (DLC) to speed up image building. (line 13).
    
*   We use [Set an Environment Variable in a Project](https://circleci.com/docs/guides/server/security/set-environment-variable/#set-an-environment-variable-in-a-project) to store credentials for Docker Hub. (line 19).
    

## Install the Docker CLI

[CircleCI Convenience Images](https://circleci.com/docs/guides/server/execute/circleci-images/) have the Docker CLI pre-installed. If you are using a third-party image that does not have the Docker CLI installed, [you need to install it](https://docs.docker.com/install/#supported-platforms) as part of your job.

```yml
      # Install via apk on alpine based images
      - run:
          name: Install Docker client
          command: apk add docker-cli
```

## Specify a Docker version for remote Docker

The `version` key for `setup_remote_docker` is not supported on CircleCI Server. Contact your system administrator for information about the Docker version installed in your remote Docker environment.

## Run Docker commands using the machine executor

The example below shows how you can build a Docker image using the `machine` executor with the default image. Note that this does not require the use of remote Docker:

```yaml
version: 2.1

jobs:
  build:
    machine:
      image: ubuntu-2604:current
    steps:
      - checkout
      # start proprietary DB using private Docker image
      # with credentials stored in the UI
      - run: |
          echo "$DOCKER_PASS" | docker login --username $DOCKER_USER --password-stdin
          docker run -d --name db company/proprietary-db:1.2.3

      # build the application image
      - run: docker build -t company/app:$CIRCLE_BRANCH .

      # deploy the image
      - run: docker push company/app:$CIRCLE_BRANCH
```

## Prefer same-region image pulls

When you set `prefer_same_region` to `true`, CircleCI attempts to pull the image from the same region as the VM on a best-effort basis. If the same-region pull fails, it falls back to pulling from the image’s original region.

```yaml
      - setup_remote_docker:
          prefer_same_region: true
```

## See also

*   [Docker Layer Caching](https://circleci.com/docs/guides/server/optimize/docker-layer-caching/)
    
*   [Primary Container](https://circleci.com/docs/reference/glossary/#primary-container)