> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt)

# Run a job in a container on your machine with Docker

The [CLI](https://circleci-public.github.io/circleci-cli/) enables you to run individual jobs on your local machine with Docker. This can be useful to run tests before pushing configuration changes, or debugging your build process without impacting your build queue.

## Prerequisites

You will need to have [Docker](https://www.docker.com/products/docker-desktop) installed on your system, as well as the most recent version of the CLI. You will also need to have a project with a valid `.circleci/config.yml` file in it.

## Running a job

The CLI allows you to run a single job from CircleCI on your desktop using Docker with the following command:

`````````
$ circleci local execute JOB_NAME
`````````

If your CircleCI configuration is set to version 2.1 or greater, you must first export your configuration to `process.yml`, and specify it when executing with the following commands:

`````````
circleci config process .circleci/config.yml > process.yml
circleci local execute -c process.yml JOB_NAME
`````````

The following commands will run an example build on your local machine on one of CircleCI’s demo applications:

`````````
git clone https://github.com/CircleCI-Public/circleci-demo-go.git
cd circleci-demo-go
circleci local execute build
`````````

The commands above will run the entire `build` job (only jobs, not workflows, can be run locally). The CLI will use Docker to pull down the requirements for the build and then execute your CI steps locally. In this case, Golang and PostgreSQL Docker images are pulled down, allowing the build to install dependencies, run the unit tests, test that the service is running, and so on.

## Limitations of running jobs locally

Although running jobs locally with `circleci` is very helpful, there are some limitations.

**Machine executor**

You cannot use the machine executor in local jobs. The machine executor requires an extra VM to run its jobs.

**Add SSH keys**

It is currently not possible to add SSH keys using the `add_ssh_keys` CLI command.

**Workflows**

The CLI tool does not provide support for running workflows. By nature, workflows leverage running jobs concurrently on multiple machines allowing you to achieve faster, more complex builds. Because the CLI is only running on your machine, it can only run single jobs (which make up parts of a workflow).

**Caching and online-only commands**

Caching is not currently supported in local jobs. When you have either a [`save_cache`](https://circleci.com/docs/reference/configuration-reference/#savecache) or [`restore_cache`](https://circleci.com/docs/reference/configuration-reference/#restorecache) step in your config, `circleci` will skip them and display a warning.

Further, not all commands may work on your local machine as they do online. For example, the Golang build reference above runs a [`store_artifacts`](https://circleci.com/docs/reference/configuration-reference/#storeartifacts) step, however, local builds will not upload artifacts. If a step is not available on a local build you will see an error in the console.

**Environment variables and contexts**

For security reasons, encrypted environment variables or contexts configured in the [web application](https://app.circleci.com/) will not be imported into local builds. As an alternative, you can specify environment variables to the CLI with the `-e` flag. See the output of the following command for more information.

`````````
circleci help build
`````````

If you have multiple environment variables, you must use the flag for each variable, for example:

`````````
circleci build -e VAR1=FOO -e VAR2=BAR
`````````