API Reference

lean backtest


Backtest a project locally using Docker.

$ lean backtest <project> [options]


Runs a local backtest in a Docker container using the quantconnect/lean Docker image. The logs of the backtest are shown in real-time and the full results are stored in the <project>/backtest/<timestamp> directory. You can use the --output option to change the output directory.

The given <project> argument must be either a project directory or a file containing the algorithm to run a backtest for. If it is a project directory the CLI looks for a main.py or Main.cs file, assuming the first file it finds to contain the algorithm to run.

If the --debug option is given this command configures the Docker container in such a way to allow debugging using your editor's debugger. The exact ways to get local debugging to work depends on your editor and language, see Debugging local backtests for more information on how to set this up.

You can use the --data-provider option to change where data is retrieved from. This option updates the Lean configuration file, so you don't need to use this option multiple times for the same data provider if you are not switching between them. Additionally, you can also use the --download-data flag as an alias for --data-provider QuantConnect, and the --data-purchase-limit option to set the maximum amount of QCC to spend during the backtest when using QuantConnect as data provider. The --data-purchase-limit option is not persistent.

The Docker image that is used contains the same libraries as the ones available on QuantConnect. If the selected project is a C# project it is compiled before starting the backtest.

By default, the official LEAN engine image is used. You can override this using the --image <value> option. Alternatively, you can set the default engine image for all commands using lean config set engine-image <value>. The image is pulled before running the backtest if it doesn't exist locally yet or if you pass the --update flag.


The lean backtest command expects the following arguments:

<project>The path to the project directory or algorithm file to run a backtest for.


The lean backtest command supports the following options:

--output <path>Directory to store results in (defaults to <project>/backtests/<timestamp>).
--detach, -dRun the backtest in a detached Docker container and return immediately. The name of the Docker container is shown before the command ends. You can use Docker's own commands to manage the detached container.
--debugEnable a certain debugging method, see Debugging local backtests for more information.
--data-provider <value>Update the Lean configuration file to retrieve data from the given provider, which must be Local, QuantConnect, or Terminal Link.
--download-dataUpdate the Lean configuration file to download data from the QuantConnect API, alias for --data-provider QuantConnect.
--data-purchase-limit <value>The maximum amount of QCC to spend on downloading data during the backtest when using QuantConnect as data provider.
--image <value>The LEAN engine image to use (defaults to quantconnect/lean:latest).
--updatePull the LEAN engine image before running the backtest.
--lean-config <path>The Lean configuration file that should be used (defaults to the nearest lean.json file).
--releaseCompile C# projects in release configuration instead of debug.
--verboseEnable debug logging.
--helpDisplay the help text of the lean backtest command and exit.

You can also see our Videos. You can also get in touch with us via Chat.

Did you find this page helpful?

Contribute to the documentation: