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 backtest. If it is a project directory, the CLI looks for a main.py or Main.cs file, assuming the first file it finds to be 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 for more information on how to set this up.

You can use the --data-provider-historical option to change where the data is retrieved. 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. The following table shows the available data providers and their required options in non-interactive mode:

--data-provider-historicalRequired Options
"Terminal Link"--terminal-link-connection-type
--terminal-link-server-auth-id if you use --terminal-link-connection-type SAPI

You can use the --download-data flag as an alias for --data-provider-historical QuantConnect. This data provider automatically downloads the required data files when your backtest requests them. After it downloads a data file, it stores it in your local data directory so that in future runs, it won't have to download it again. If the file contain data for multiple days (for example, daily Equity price data files), the ApiDataProvider re-downloads the file if your local version is at least 7 days old. To adjust this setting, update the downloader-data-update-period value in your Lean configuration file.

You can also use the --data-purchase-limit option to set the maximum amount of QuantConnect Credit (QCC) to spend during the backtest when using QuantConnect as data provider. The --data-purchase-limit option is not persistent.

The Docker image that's 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 backtest.


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 for more information.
--data-provider-historicalThe historical data source.
--iqfeed-iqconnect <path>The path to your IQConnect binary.
--iqfeed-username <value>Your IQFeed username.
--iqfeed-password <value>Your IQFeed password.
--iqfeed-version <value>The product version of your IQFeed developer account.
--iqfeed-hostThe IQFeed host address.
--polygon-api-key <value>Your Polygon.io API Key.
--iex-cloud-api-keyYour IEX Cloud API Key.
--iex-price-planYour IEX Cloud price plan. Launch, Grow, or Enterprise.
--alpha-vantage-api-keyYour Alpha Vantage API Key.
--alpha-vantage-price-planYour Alpha Vantage price plan. Free, Plan30, Plan75, Plan150, Plan300, Plan600, or Plan1200.
--terminal-link-connection-type <value>The Terminal Link connection type, which must be SAPI or DAPI.
--terminal-link-server-auth-id <value>Your unique user identifier (UUID). The UUID is a unique integer identifier that's assigned to each Bloomberg Anywhere user. If you don't know your UUID, contact Bloomberg.
--terminal-link-environment <value>The environment to run in, which must be Production or Beta.
--terminal-link-server-host <value>The host on which the Terminal Link server is running.
--terminal-link-server-port <value>The port on which the Terminal Link server is running.
--terminal-link-openfigi-api-key <value>The Open FIGI API key to use for mapping Options.
--download-dataUpdate the Lean configuration file to download data from the QuantConnect API, alias for --data-provider-historical QuantConnect.
--data-purchase-limit <value>The maximum amount of QCC to spend on downloading data during the backtest when using QuantConnect as data provider.
--releaseCompile C# projects in release configuration instead of debug.
--image <value>The LEAN engine image to use (defaults to quantconnect/lean:latest).
--python-venv <value>The path of the python virtual environment to use.
--updatePull the LEAN engine image before running the backtest.
--no-updateUse the local LEAN engine image instead of pulling the latest version.
--lean-config <path>The Lean configuration file that should be used (defaults to the nearest lean.json file).
--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 Discord.

Did you find this page helpful?

Contribute to the documentation: