API Reference

lean backtest


Backtest a project locally using Docker.

$ lean backtest [OPTIONS] PROJECT


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 <directory>Directory to store results in (defaults to PROJECT/backtests/TIMESTAMP)
-d, --detachRun the backtest in a detached Docker container and return immediately
--debug <enum: pycharm
Enable a certain debugging method (see --help for more information)
--data-provider-historical <enum: Interactive Brokers
                                  Coinbase Advanced Trade
                                  Terminal Link
Update the Lean configuration file to retrieve data from the given historical provider
--ib-user-name <string>Your Interactive Brokers username
--ib-account <string>Your Interactive Brokers account id
--ib-password <string>Your Interactive Brokers password
--ib-weekly-restart-utc-time <string>Weekly restart UTC time (hh:mm:ss). Each week on Sunday your algorithm is restarted at this time, and will require 2FA verification. This is required by Interactive Brokers. Use this option explicitly to override the default value. (Optional)
--oanda-account-id <string>Your OANDA account id
--oanda-access-token <string>Your OANDA API token
--oanda-environment <enum: Practice|Trade>The environment to run in, Practice for fxTrade Practice, Trade for fxTrade
--bitfinex-api-key <string>Your Bitfinex API key
--bitfinex-api-secret <string>Your Bitfinex API secret
--coinbase-api-key <string>Your Coinbase Advanced Trade API key
--coinbase-api-secret <string>Your Coinbase Advanced Trade API secret
--binance-exchange-name <enum: Binance
Binance exchange name [Binance, BinanceUS, Binance-USDM-Futures, Binance-COIN-Futures]
--binance-api-key <string>Your Binance API key
--binanceus-api-key <string>Your Binance API key
--binance-api-secret <string>Your Binance API secret
--binanceus-api-secret <string>Your Binance API secret
--kraken-api-key <string>Your Kraken API key
--kraken-api-secret <string>Your Kraken API secret
--kraken-verification-tier <enum: Starter|Intermediate|Pro>Your Kraken Verification Tier
--iqfeed-iqconnect <string>The path to the IQConnect binary
--iqfeed-username <string>Your IQFeed username
--iqfeed-password <string>Your IQFeed password
--iqfeed-version <string>The product version of your IQFeed developer account
--iqfeed-host <string>The IQFeed host address
--polygon-api-key <string>Your Polygon.io API Key
--factset-auth-config-file <file>The path to the FactSet authentication configuration file
--iex-cloud-api-key <string>Your iexcloud.io API token publishable key
--iex-price-plan <enum: Launch|Grow|Enterprise>Your IEX Cloud Price plan
--alpha-vantage-api-key <string>Your Alpha Vantage Api Key
--alpha-vantage-price-plan <enum: Free
Your Alpha Vantage Premium API Key plan
--coinapi-api-key <string>Your coinapi.io Api Key
--coinapi-product <enum: Free
CoinApi pricing plan (https://www.coinapi.io/market-data-api/pricing)
--thetadata-ws-url <string>The ThetaData host address (Optional)
--thetadata-rest-url <string>The ThetaData host address (Optional)
--thetadata-subscription-plan <enum: Free
Your ThetaData subscription price plan
--terminal-link-connection-type <enum: DAPI|SAPI>Terminal Link Connection Type [DAPI, SAPI]
--terminal-link-server-auth-id <string>The Auth ID of the TerminalLink server
--terminal-link-environment <enum: Production|Beta>The environment to run in
--terminal-link-server-host <string>The host of the TerminalLink server
--terminal-link-server-port <integer>The port of the TerminalLink server
--terminal-link-openfigi-api-key <string>The Open FIGI API key to use for mapping options
--bybit-api-key <string>Your Bybit API key
--bybit-api-secret <string>Your Bybit API secret
--bybit-vip-level <enum: VIP0
Your Bybit VIP Level
--download-dataUpdate the Lean configuration file to download data from the QuantConnect API, alias for --data-provider-historical QuantConnect
--data-purchase-limit <integer>The maximum amount of QCC to spend on downloading data during the backtest when using QuantConnect as historical data provider
--releaseCompile C# projects in release configuration instead of debug
--image <string>The LEAN engine image to use (defaults to quantconnect/lean:latest)
--python-venv <string>The path of the python virtual environment to be used
--updatePull the LEAN engine image before running the backtest
--backtest-name <string>Backtest name
--extra-docker-config <string>Extra docker configuration as a JSON string. For more information https://docker- py.readthedocs.io/en/stable/containers.html
--no-updateUse the local LEAN engine image instead of pulling the latest version
--lean-config <file>The Lean configuration file that should be used (defaults to the nearest lean.json)
--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: