---
title: "lean backtest"
description: "API reference for the command `lean backtest` in command line console."
canonical: https://www.quantconnect.com/docs/v2/lean-cli/api-reference/lean-backtest
markdown: https://www.quantconnect.com/docs/v2/lean-cli/api-reference/lean-backtest.md
language: python
source: https://github.com/QuantConnect/Documentation/tree/master/05%20Lean%20CLI/99%20API%20Reference/01%20lean%20backtest
modified: 2026-10-29
index: https://www.quantconnect.com/llms.txt
---

# lean backtest

[Documentation](https://www.quantconnect.com/docs/v2.md) > [Lean CLI](https://www.quantconnect.com/docs/v2/lean-cli.md) > [API Reference](https://www.quantconnect.com/docs/v2/lean-cli/api-reference.md) > lean backtest

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

## Introduction

Backtest a project locally using Docker.

```
$ lean backtest [OPTIONS] PROJECT
```

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.

## Description

Runs a local backtest in a Docker container using the [quantconnect/lean](https://hub.docker.com/r/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](https://www.quantconnect.com/docs/v2/lean-cli/backtesting/debugging.md) 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](https://www.quantconnect.com/docs/v2/lean-cli/initialization/configuration.md#03-Lean-Configuration), 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-historical` | Required Options |
| --- | --- |
| `Alpaca` | `--alpaca-environment` |
| `AlphaVantage` | `--alpha-vantage-api-key` |
| `AlphaVantage` | `--alpha-vantage-price-plan` |
| `Binance` | `--binance-exchange-name` |
| `Binance` | `--binance-api-key` or `--binanceus-api-key` |
| `Binance` | `--binance-api-secret` or `--binanceus-api-secret` |
| `Bybit` | `--bybit-api-key` |
| `Bybit` | `--bybit-api-secret` |
| `CoinApi` | `--coinapi-api-key` |
| `CoinApi` | `--coinapi-product` |
| `"Coinbase Advanced Trade"` | `--coinbase-api-name` |
| `"Coinbase Advanced Trade"` | `--coinbase-api-private-key` |
| `FactSet` | `--factset-auth-config-file` |
| `IEX` | `--iex-cloud-api-key` |
| `IEX` | `--iex-price-plan` |
| `"Interactive Brokers"` | `--ib-user-name` |
| `"Interactive Brokers"` | `--ib-account` |
| `"Interactive Brokers"` | `--ib-password` |
| `IQFeed` | `--iqfeed-iqconnect` |
| `IQFeed` | `--iqfeed-username` |
| `IQFeed` | `--iqfeed-password` |
| `IQFeed` | `--iqfeed-version` |
| `IQFeed` | `--iqfeed-host` |
| `Kraken` | `--kraken-api-key` |
| `Kraken` | `--kraken-api-secret` |
| `Kraken` | `--kraken-verification-tier` |
| `Local` | N/A |
| `Oanda` | `--oanda-account-id` |
| `Oanda` | `--oanda-access-token` |
| `Oanda` | `--oanda-environment` |
| `Polygon` | `--polygon-api-key` |
| `QuantConnect` | N/A |
| `"Quant Bridge"` | `--quant-bridge-connection-type` |
| `"Quant Bridge"` | `--quant-bridge-environment` |
| `"Quant Bridge"` | `--quant-bridge-server-host` |
| `"Quant Bridge"` | `--quant-bridge-server-port` |
| `"Quant Bridge"` | `--quant-bridge-emsx-broker` |
| `"Quant Bridge"` | `--quant-bridge-openfigi-api-key` |
| `"Quant Bridge"` | `--quant-bridge-server-auth-id` if you use `--quant-bridge-connection-type SAPI` |
| `ThetaData` | `--thetadata-subscription-plan` |
| `TradeStation` | N/A |

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](https://www.quantconnect.com/docs/v2/lean-cli/initialization/configuration.md#03-Lean-Configuration) file.

You can also use the `--data-purchase-limit` option to set the maximum amount of [QuantConnect Credit](https://www.quantconnect.com/docs/v2/cloud-platform/organizations/credit.md) (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](https://www.quantconnect.com/docs/v2/lean-cli/projects/libraries/third-party-libraries.md). 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.

## Arguments

The `lean backtest` command expects the following arguments:

| Argument | Description |
| --- | --- |
| `<project>` | The path to the project directory or algorithm file to backtest. |

## Options

The `lean backtest` command supports the following options:

| Option | Description |
| --- | --- |
| `--output <directory>` | Directory to store results in (defaults to PROJECT/backtests/TIMESTAMP) |
| `-d, --detach` | Run the backtest in a detached Docker container and return immediately |
| `--debug <enum: pycharm                ptvsd                debugpy                vsdbg                rider                local-platform>` | Enable a certain debugging method (see --help for more information) |
| `--data-provider-historical <enum: Interactive Brokers                                   Oanda                                   Bitfinex                                   Coinbase Advanced Trade                                   Binance                                   Kraken                                   CharlesSchwab                                   IQFeed                                   Polygon                                   FactSet                                   AlphaVantage                                   CoinApi                                   ThetaData                                   QuantConnect                                   Local                                   Quant Bridge                                   Bybit                                   TradeStation                                   Alpaca                                   Tastytrade                                   Eze                                   dYdX                                   Databento                                   Webull                                   Public>` | 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-host <string>` | External Interactive Brokers Gateway Host (Optional) |
| `--ib-port <string>` | External Interactive Brokers Gateway Port (Optional) |
| `--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-name <string>` | Your Coinbase Advanced Trade API name from file |
| `--coinbase-api-private-key <string>` | Your Coinbase Advanced Trade API private key from file |
| `--binance-exchange-name <enum: Binance                                BinanceUS                                Binance-USDM-Futures                                Binance-COIN-Futures>` | 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 |
| `--charles-schwab-user-name <string>` | Your Charles Schwab login ID |
| `--charles-schwab-account-number <string>` | The CharlesSchwab account number |
| `--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 (Optional) |
| `--polygon-api-key <string>` | Your Polygon.io API Key |
| `--polygon-license-type <enum: Individual\|Business>` | Select your Polygon.io subscription plan (Optional) |
| `--factset-auth-config-file <file>` | The path to the FactSet authentication configuration file |
| `--alpha-vantage-api-key <string>` | Your Alpha Vantage Api Key |
| `--alpha-vantage-price-plan <enum: Free                                   Plan30                                   Plan75                                   Plan150                                   Plan300                                   Plan600                                   Plan1200>` | Your Alpha Vantage Premium API Key plan |
| `--coinapi-api-key <string>` | Your coinapi.io Api Key |
| `--coinapi-product <enum: Free                          Startup                          Streamer                          Professional                          Enterprise>` | 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                                      Value                                      Standard                                      Pro>` | Your ThetaData subscription price plan |
| `--quant-bridge-connection-type <enum: DAPI\|SAPI>` | Quant Bridge Connection Type [DAPI, SAPI] |
| `--quant-bridge-environment <enum: Production\|Beta>` | The environment to run in |
| `--quant-bridge-server-host <string>` | The host of the QuantBridge server |
| `--quant-bridge-server-port <integer>` | The port of the QuantBridge server |
| `--quant-bridge-openfigi-api-key <string>` | The Open FIGI API key to use for mapping options |
| `--quant-bridge-server-auth-id <string>` | The Auth ID of the QuantBridge server |
| `--bybit-api-key <string>` | Your Bybit API key |
| `--bybit-api-secret <string>` | Your Bybit API secret |
| `--trade-station-environment <enum: live\|paper>` | Whether Live or Paper environment should be used |
| `--trade-station-account-id <string>` | The TradeStation account Id |
| `--alpaca-environment <enum: live\|paper>` | Whether Live or Paper environment should be used |
| `--tastytrade-account-number <string>` | The Tastytrade account number |
| `--eze-domain <string>` | Examples (broker provided): LIGHTSPEED, LIGHTSPEEDDELAY |
| `--eze-locale <string>` | Examples (broker provided): GLOBAL, AMERICAS, LIVE, DELAYED |
| `--eze-user-name <string>` | Your Eze Brokers username |
| `--eze-password <string>` | Your Eze Brokers password |
| `--dydx-private-key-hex <string>` | Your dYdX API private key in hex format |
| `--dydx-address <string>` | Your dYdX wallet address |
| `--dydx-subaccount-number <integer>` | Your dYdX subaccount number |
| `--databento-api-key <string>` | Your Databento.com API Key |
| `--webull-environment <enum: live\|paper>` | Whether Live or Paper environment should be used |
| `--webull-app-key <string>` | Your Webull App Key |
| `--webull-app-secret <string>` | Your Webull App Secret |
| `--webull-account-id <string>` | Your Webull account id |
| `--webull-use-2fa <boolean>` | Whether two-factor authentication (2FA) should be used (Optional) |
| `--public-secret-key <string>` | Your Public.com API secret key |
| `--public-account-number <string>` | Your Public.com account number. Public lets you have more than one account, so this picks which one to trade |
| `--download-data` | Update 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 |
| `--release` | Compile 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 |
| `--update` | Pull 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-update` | Use the local LEAN engine image instead of pulling the latest version |
| `--parameter <<string> <string>>...` | Key-value pairs to pass as backtest parameters. Values can be string, int, or float. Example: --parameter symbol AAPL --parameter period 10 --parameter threshold 0.05 |
| `--lean-config <file>` | The Lean configuration file that should be used (defaults to the nearest lean.json) |
| `--verbose` | Enable debug logging |
| `--help` | Display the help text of the `lean backtest` command and exit |