--- title: "Deployment" description: "Learn how to deploy a backtest in Lean CLI." canonical: https://www.quantconnect.com/docs/v2/lean-cli/backtesting/deployment markdown: https://www.quantconnect.com/docs/v2/lean-cli/backtesting/deployment.md language: python source: https://github.com/QuantConnect/Documentation/tree/master/05%20Lean%20CLI/08%20Backtesting/01%20Deployment modified: 2026-10-31 index: https://www.quantconnect.com/llms.txt --- # Deployment [Documentation](https://www.quantconnect.com/docs/v2.md) > [Lean CLI](https://www.quantconnect.com/docs/v2/lean-cli.md) > Backtesting > Deployment > Code examples are shown in Python. Append `?lang=csharp` to this URL for the C# version of this page. ## Introduction Backtesting is a way to test your algorithm on historical data. The CLI makes backtesting easier by providing simple commands to backtest your algorithms locally or in QuantConnect Cloud. 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. ## Run Local Backtests By default, local backtests run in the LEAN engine in the [quantconnect/lean](https://hub.docker.com/r/quantconnect/lean) Docker image. This Docker image contains all the [libraries available on QuantConnect](https://www.quantconnect.com/docs/v2/lean-cli/projects/libraries/third-party-libraries.md), meaning your algorithm also has access to those libraries. If the specified project is a C# project, it is first compiled using the same Docker image. See [Third-Party Libraries](https://www.quantconnect.com/docs/v2/lean-cli/projects/libraries/third-party-libraries.md) to learn how to use custom libraries and see [Custom Docker Images](https://www.quantconnect.com/docs/v2/lean-cli/projects/custom-docker-images.md) to learn how to build and use custom Docker images. Because algorithms run in a Docker container, `localhost` does not point to your computer's `localhost`. Substitute `localhost` with `host.docker.internal` if your algorithm needs to connect to other services running on your computer. In other words, instead of connecting to `http://localhost:/`, connect to `http://host.docker.internal:/`. You can run local backtests with the regular version of the LEAN engine or a custom version. ### Regular LEAN Engine Follow these steps to run a local backtest with the latest version of LEAN engine: 1. Get the data your project needs from one of the following sources: - [Purchase the data](https://www.quantconnect.com/docs/v2/lean-cli/datasets/quantconnect.md) from QuantConnect. - Get the data from another data provider, such as [Polygon](https://www.quantconnect.com/docs/v2/lean-cli/datasets/polygon.md), [Databento](https://www.quantconnect.com/docs/v2/lean-cli/datasets/databento.md), or [Theta Data](https://www.quantconnect.com/docs/v2/lean-cli/datasets/theta-data.md). - [Import your own data](https://www.quantconnect.com/docs/v2/lean-cli/datasets/custom-data.md). 2. Open a terminal in the [organization workspace](https://www.quantconnect.com/docs/v2/lean-cli/initialization/organization-workspaces.md) that contains the project you want to backtest. 3. Run `lean backtest ""` to run a local backtest for the project in `. / `. ``` $ lean backtest "My Project" 20210322 17:27:46.658 TRACE:: Engine.Main(): LEAN ALGORITHMIC TRADING ENGINE v2.5.0.0 Mode: DEBUG (64bit) 20210322 17:27:46.664 TRACE:: Engine.Main(): Started 5:27 PM Successfully ran 'My Project' in the 'backtesting' environment and stored the output in 'My Project/backtests/2021-03-22_18-51-28' ``` 4. View the result in the ` / backtests / ` directory. Results are stored in JSON files and can be analyzed in a [local research environment](https://www.quantconnect.com/docs/v2/lean-cli/research.md#02-Start-the-Research-Environment). You can save results to a different directory by providing the `--output ` option in step 3. ``` $ lean backtest "My Project" --output "My Project/custom-output" 20210322 17:27:46.658 TRACE:: Engine.Main(): LEAN ALGORITHMIC TRADING ENGINE v2.5.0.0 Mode: DEBUG (64bit) 20210322 17:27:46.664 TRACE:: Engine.Main(): Started 5:27 PM Successfully ran 'My Project' in the 'backtesting' environment and stored the output in 'My Project/custom-output' ``` To view the results in the terminal while the backtest runs, run the backtest from the [terminal UI](https://www.quantconnect.com/docs/v2/lean-cli/projects/ui.md). ### Custom LEAN Engine Follow these steps to run a local backtest with a custom version of the LEAN engine: 1. Get the data your project needs from one of the following sources: - [Purchase the data](https://www.quantconnect.com/docs/v2/lean-cli/datasets/quantconnect.md) from QuantConnect. - Get the data from another data provider, such as [Polygon](https://www.quantconnect.com/docs/v2/lean-cli/datasets/polygon.md), [Databento](https://www.quantconnect.com/docs/v2/lean-cli/datasets/databento.md), or [Theta Data](https://www.quantconnect.com/docs/v2/lean-cli/datasets/theta-data.md). - [Import your own data](https://www.quantconnect.com/docs/v2/lean-cli/datasets/custom-data.md). 2. View the available versions on the [quantconnect/lean Docker Hub tags page](https://hub.docker.com/r/quantconnect/lean/tags). 3. Copy the name of the tag that you want to run. 4. Run `lean backtest " --image quantconnect/lean:"` to run a local backtest for the project in `. / `. ``` $ lean backtest "My Project" --image quantconnect/lean:11154 Pulling quantconnect/lean:11154... 20210322 17:27:46.658 TRACE:: Engine.Main(): LEAN ALGORITHMIC TRADING ENGINE v2.5.0.0 Mode: DEBUG (64bit) 20210322 17:27:46.664 TRACE:: Engine.Main(): Started 5:27 PM ``` ### Parameters To run a local backtest with specific [parameters](https://www.quantconnect.com/docs/v2/writing-algorithms/optimization/parameters.md), use the `--parameter name value` option. ``` $ lean backtest "My Project" --parameter ema_fast 100 --parameter ema_slow 50 20210322 17:27:46.658 TRACE:: Engine.Main(): LEAN ALGORITHMIC TRADING ENGINE v2.5.0.0 Mode: DEBUG (64bit) 20210322 17:27:46.664 TRACE:: Engine.Main(): Started 5:27 PM Successfully ran 'My Project' in the 'backtesting' environment and stored the output in 'My Project/backtests/2021-03-22_18-51-28' ``` ### Data Providers When you run a local backtest, the default data provider is your local machine. To use data from [QuantConnect Cloud](https://www.quantconnect.com/docs/v2/lean-cli/backtesting/deployment.md#04-Download-Datasets-During-Backtests), a brokerage, or a third-party data provider, include the `--data-provider-historical` option. To view what brokerages and third-party data providers are available, see [the reference page for this command](https://www.quantconnect.com/docs/v2/lean-cli/api-reference/lean-backtest.md). ### Required Datasets To run backtests with Equity or Equity Option data, download the [download the US Equity Security Master](https://www.quantconnect.com/datasets/quantconnect-us-equity-security-master/cli). To run backtests with Futures data, [download the US Futures Security Master](https://www.quantconnect.com/datasets/quantconnect-us-futures-security-master/cli). ### US Equity Options Algorithms Follow these steps to run a local US Equity Options backtest: 1. Download the [US Equity Security Master](https://www.quantconnect.com/datasets/quantconnect-us-equity-security-master/cli) dataset. ``` $ lean data download --dataset "US Equity Security Master" ``` 2. Download minute resolution trade data from the [US Equity](https://www.quantconnect.com/datasets/algoseek-us-equities/cli) dataset. ``` $ lean data download --dataset "US Equities" --data-type "Trade" --ticker "SPY" --resolution "Minute" --start "20210101" --end "20210720" ``` 3. Download minute resolution trade and quote data from the [US Equity Options](https://www.quantconnect.com/datasets/algoseek-us-equity-options/cli) dataset. ``` $ lean data download --dataset "US Equity Options" --data-type "Trade" --option-style "American" --ticker "SPY" --resolution "Minute" --start "20210101" --end "20210720" $ lean data download --dataset "US Equity Options" --data-type "Quote" --option-style "American" --ticker "SPY" --resolution "Minute" --start "20210101" --end "20210720" ``` 4. [Create a new local project](https://www.quantconnect.com/docs/v2/lean-cli/projects/project-management.md#02-Create-Projects). ``` $ lean project-create --language python "" ``` You can use the following example algorithm: ```python # Buy a SPY call Option contract and hold it until expiry. class UsEquityOptionsDemoAlgorithm(QCAlgorithm): def initialize(self) -> None: self.set_start_date(2024, 1, 1) self.set_end_date(2024, 3, 1) self.set_cash(100000) equity = self.add_equity("SPY", Resolution.MINUTE) option = self.add_option(equity.symbol, Resolution.MINUTE) option.set_filter(-5, 5, 30, 60) self._contract = None def on_data(self, slice: Slice) -> None: if self._contract is not None: return for chain in slice.option_chains.values(): calls = [c for c in chain if c.right == OptionRight.CALL] if not calls: continue contract = sorted(calls, key=lambda c: abs(c.strike - c.underlying_last_price))[0] self.market_order(contract.symbol, 1) self._contract = contract.symbol ``` If you have the latest version of LEAN and you get different [overall statistics](https://www.quantconnect.com/docs/v2/cloud-platform/backtesting/results.md#09-Key-Statistics) when you run the algorithm on your local machine versus in the cloud, delete your [local data files](https://www.quantconnect.com/docs/v2/lean-cli/datasets/format-and-storage.md#02-Default-Location) and [re-download them](https://www.quantconnect.com/docs/v2/lean-cli/datasets/quantconnect.md). Some of your local files may be outdated and the preceding download commands didn't update them. The following table shows a breakdown of the data costs for this example algorithm: | Dataset | Initial Cost (USD) | Update Cost (USD) | | --- | --- | --- | | US Equity Security Master | $1,200/year | $1,200/year | | US Equity | $7.05 | $0.05/day | | US Equity Options | $41.70 | $0.30/day | ## Run Cloud Backtests When you run a backtest in QuantConnect Cloud, it uses the data from the [Dataset Market](https://www.quantconnect.com/datasets). Follow these steps to run a cloud backtest: 1. [Log in](https://www.quantconnect.com/docs/v2/lean-cli/initialization/authentication.md#02-Log-In) to the CLI if you haven't done so already. 2. Open a terminal in the [organization workspace](https://www.quantconnect.com/docs/v2/lean-cli/initialization/organization-workspaces.md) that contains the project you want to backtest. 3. Run `lean cloud backtest "" --push --open` to push `. / ` to the cloud, run a cloud backtest for the project, and open the results in the browser. ``` $ lean cloud backtest "My Project" --push --open [1/1] Pushing 'My Project' Successfully updated cloud file 'My Project/main.py' Started compiling project 'My Project' Successfully compiled project 'My Project' Started backtest named 'Muscular Black Chinchilla' for project 'My Project' ``` 4. Inspect the result in the browser, which opens automatically after the backtest finishes. To view the results in the terminal while the backtest runs, run the backtest from the [terminal UI](https://www.quantconnect.com/docs/v2/lean-cli/projects/ui.md). To run a cloud backtest with specific [parameters](https://www.quantconnect.com/docs/v2/writing-algorithms/optimization/parameters.md), use the `--parameter name value` option. ``` $ lean cloud backtest "My Project" --push --open --parameter ema_fast 100 --parameter ema_slow 50 [1/1] Pushing 'My Project' Successfully updated cloud file 'My Project/main.py' Started compiling project 'My Project' Successfully compiled project 'My Project' Started backtest named 'Muscular Black Chinchilla' for project 'My Project' ``` ## Download Datasets During Backtests An alternative to manually downloading all the data you need before you run a backtest is to use the `ApiDataProvider` in LEAN. 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 files contain data for multiple days (for example, daily Equity price data files), the `ApiDataProvider` re-downloads the files if your local files are 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. Follow these steps to use the `ApiDataProvider` to automatically download the data you need: 1. [Log in](https://www.quantconnect.com/docs/v2/lean-cli/initialization/authentication.md#02-Log-In) to the CLI if you haven't done so already. 2. Open a terminal in the [organization workspace](https://www.quantconnect.com/docs/v2/lean-cli/initialization/organization-workspaces.md) that contains the project you want to backtest. 3. Run `lean backtest "" --download-data` to run a local backtest for the project in `. / ` and update the Lean configuration to use the `ApiDataProvider`. ``` $ lean backtest "My Project" --download-data 20210322 17:27:46.658 TRACE:: Engine.Main(): LEAN ALGORITHMIC TRADING ENGINE v2.5.0.0 Mode: DEBUG (64bit) 20210322 17:27:46.664 TRACE:: Engine.Main(): Started 5:27 PM Successfully ran 'My Project' in the 'backtesting' environment and stored the output in 'My Project/backtests/2021-03-22_18-51-28' ``` Setting the `--download-data` flag updates your Lean configuration. This means that you only need to use the flag once, all future backtests will automatically use the `ApiDataProvider`. Follow these steps to revert the Lean configuration changes so that it uses only local data again: 1. Open a terminal in your [organization workspace](https://www.quantconnect.com/docs/v2/lean-cli/initialization/organization-workspaces.md). 2. Run `lean backtest "" --data-provider-historical Local` to run a local backtest for the project in `. / ` and update the Lean configuration to only use local data. ``` $ lean backtest "My Project" --data-provider-historical Local 20210322 17:27:46.658 TRACE:: Engine.Main(): LEAN ALGORITHMIC TRADING ENGINE v2.5.0.0 Mode: DEBUG (64bit) 20210322 17:27:46.664 TRACE:: Engine.Main(): Started 5:27 PM Successfully ran 'My Project' in the 'backtesting' environment and stored the output in 'My Project/backtests/2021-03-22_18-51-28' ``` The `--data-provider-historical` option updates your [Lean configuration](https://www.quantconnect.com/docs/v2/lean-cli/initialization/configuration.md#03-Lean-Configuration). This means that you only need to use the option once, all future backtests will automatically use the newly configured data provider. By default the `ApiDataProvider` does not have a spending limit and will keep downloading files until your QuantConnect organization runs out of QuantConnect Credit (QCC). You can use the `--data-purchase-limit ` option to set the QCC spending limit for the backtest. All the options documented above are also available on the `lean research` command. ## Get Backtest Id To get the Id of a local backtest, check the name of the ` / / / .json` file. An example local backtest Id is 1710698424. To get the Id of a cloud backtest, check the output of the `lean cloud backtest` command in the terminal. If you no longer have the output, [get the backtest Id from the Algorithm Lab](https://www.quantconnect.com/docs/v2/cloud-platform/backtesting/getting-started.md#07-Get-Backtest-Id). An example cloud backtest Id is 8b16cec0c44f75188d82f9eadb310e17.