Start Building for Free

Run Docker commands

2 weeks ago3 min read
Server v4.x
Server v3.x
On This Page

Use the remote Docker environment (setup_remote_docker) to build Docker images in the Docker execution environment. When you use the remote Docker environment for a job, any Docker commands you run in your job execute locally on the virtual machine used to spin up your primary Docker container.


To build Docker images for deployment using the Docker execution environment, you must use the setup_remote_docker key. If your job requires docker or docker-compose commands, add the setup_remote_docker step into your .circleci/config.yml:

      - image: cimg/base:2022.06
      # ... steps for building/testing app ...
      - setup_remote_docker

When setup_remote_docker executes, any Docker commands you use will execute locally on the virtual machine used to spin up containers for your job.

In the CircleCI web app, jobs that run in the remote Docker environment have the Remote Docker label.

Remote Docker label


For technical specifications and pricing information for the remote Docker environment, see Discuss. For CircleCI server installations, contact the systems administrator for specifications.

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 using the Docker executor, with remote Docker:

version: 2.1

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

      - setup_remote_docker:
          docker_layer_caching: true

      # build and push Docker image
      - run: |
          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 break down of what is happening during this build’s execution:

Resource classes

The resource class for the remote Docker environment is determined by the configuration of the primary container.

For x86 architecture the equivalent Linux VM resource class is used for remote Docker, relative to how the primary container is configured, apart from if you are using small or medium+, in which case medium and large are used, respectively. For a full list of available Linux VM resource classes see the Configuration Reference.

For Arm, the equivalent Arm VM resource class will be used. For a full list of available Arm VM resource classes see the Configuration Reference.

For credit/pricing information, see the Resource class product page.

Install the Docker CLI

The CircleCI convenience images for the Docker executor come with the Docker CLI pre-installed. If you are using a third-party image for your primary container that doesn’t already have the Docker CLI installed, then you will need to install it as part of your job before calling any docker commands.

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

Specify a Docker version for remote Docker

To optionally specify a Docker version, you can set it as a version attribute with supported tags:

      - setup_remote_docker:
          version: edge

CircleCI supports the tags listed below for remote Docker, as per our Remote Docker tagging policy.

For x86 and Arm architecture, the following tags are available:

  • default

  • edge

  • previous

The above tags resolve to the latest supported Docker version, which is Docker 24.

To use Docker 23, the previous Docker release, use the following tag:

  • docker23

To use Docker 24, patch updates will occur until Docker 25 is released, use the following tag:

  • docker24

To use the current deprecated version, Docker 20, use 20.10.24

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 - this does not require the use of remote Docker:

version: 2.1

      image: ubuntu-2204:2022.04.2
      - 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

Suggest an edit to this page

Make a contribution
Learn how to contribute