---
title: "Custom Docker Images"
description: "Learn how to create and use custom docker image to run your algorithm in Lean CLI."
canonical: https://www.quantconnect.com/docs/v2/lean-cli/projects/custom-docker-images
markdown: https://www.quantconnect.com/docs/v2/lean-cli/projects/custom-docker-images.md
language: python
source: https://github.com/QuantConnect/Documentation/tree/master/05%20Lean%20CLI/06%20Projects/10%20Custom%20Docker%20Images
modified: 2026-10-28
index: https://www.quantconnect.com/llms.txt
---

# Custom Docker Images

[Documentation](https://www.quantconnect.com/docs/v2.md) > [Lean CLI](https://www.quantconnect.com/docs/v2/lean-cli.md) > Projects > Custom Docker Images

> Code examples are shown in Python. Append `?lang=csharp` to this URL for the C# version of this page.

## Introduction

By default, the CLI uses the official LEAN Docker images when running the LEAN engine or the research environment. However, the CLI also supports custom Docker images, making it possible to use your own version of LEAN. To make this feature easier to use, the CLI is also capable of building Docker images of your own version of LEAN using a single command.

To use the CLI, you must be a member in an [organization](https://www.quantconnect.com/docs/v2/cloud-platform/organizations/tier-features.md) on a paid tier.

## Using Custom Images

Follow these steps to make the CLI use custom Docker images when running the LEAN engine or the research environment:

1. Open a terminal.
2. Run `lean config set engine-image <value>`, where `<value>` is the full name of your Docker image containing the LEAN engine (example: `quantconnect/lean:latest`).

   ```
   $ lean config set engine-image quantconnect/lean:latest
   Successfully updated the value of 'engine-image' to 'quantconnect/lean:latest'
   ```
3. Run `lean config set research-image <value>`, where `<value>` is the full name of your Docker image containing the research environment (example: `quantconnect/research:latest`).

   ```
   $ lean config set research-image quantconnect/research:latest
   Successfully updated the value of 'research-image' to 'quantconnect/research:latest'
   ```

Follow these steps to revert the CLI to using the default Docker images when running the LEAN engine or the research environment:

1. Open a terminal.
2. Run `lean config unset engine-image` to configure the CLI to use the default engine image instead of a custom one.

   ```
   $ lean config unset engine-image
   Successfully unset 'engine-image'
   ```
3. Run `lean config unset research-image` to configure the CLI to use the default research image instead of a custom one.

   ```
   $ lean config unset research-image
   Successfully unset 'research-image'
   ```

## Building Custom Images

Follow these steps to build custom LEAN Docker images using the CLI:

1. Create a new directory that will hold the LEAN repository.
2. Clone the [`QuantConnect / Lean`](https://github.com/QuantConnect/Lean) GitHub repository using `git` or download and extract the latest [master branch archive](https://github.com/QuantConnect/Lean/archive/refs/heads/master.zip). Save this repository to a directory called `Lean` in the directory created in step 1.
3. Make your changes to LEAN.
4. Open a terminal in the directory created in step 1.
5. Run `lean build` to build the foundation image, compile LEAN, build the engine image, and build the research image.

   ```
   $ lean build
   Building 'lean-cli/foundation:latest' from '/home/johndoe/QuantConnect/Lean/DockerfileLeanFoundation'
   Compiling the C# code in '/home/johndoe/QuantConnect/Lean'
   Building 'lean-cli/engine:latest' from '/home/johndoe/QuantConnect/Lean/Dockerfile' using 'lean-cli/foundation:latest' as base image
   Building 'lean-cli/research:latest' from '/home/johndoe/QuantConnect/Lean/DockerfileJupyter' using 'lean-cli/engine:latest' as base image
   Setting default engine image to 'lean-cli/engine:latest'
   Setting default research image to 'lean-cli/research:latest'
   ```

   After running this command the CLI uses your newly built images instead of the official ones.

By default the `lean build` command tags all custom images with `latest`. You can specify a different tag using the `--tag <value>` option.

If you haven't changed the foundation Dockerfile, the CLI automatically skips building the custom foundation image and uses the official `quantconnect/lean:foundation` image instead.