Backtesting

By default, local backtests run in the LEAN engine in the quantconnect/lean Docker image. This Docker image contains all the libraries available on QuantConnect, 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 to learn how to use custom libraries and see Custom Docker Images 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:<port>/, connect to http://host.docker.internal:<port>/.

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. Set up your local data for all the data required by your project.
2. Open a terminal in the organization workspace that contains the project you want to backtest.
3. Run lean backtest "<projectName>" to run a local backtest for the project in . / <projectName>.

   $ 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 <projectName> / backtests / <timestamp> directory. Results are stored in JSON files and can be analyzed in a local research environment. You can save results to a different directory by providing the --output <path> 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'

Custom LEAN Engine

Follow these steps to run a local backtest with a custom version of the LEAN engine:

1. Set up your local data for all the data required by your project.
2. View the available versions on the quantconnect/lean Docker Hub tags page.
3. Copy the name of the tag that you want to run.
4. Run lean backtest "<projectName> --image quantconnect/lean:<tagFromStep2>" to run a local backtest for the project in . / <projectName>.

   $ 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

Data Providers

When you run a local backtest, the default data provider is your local machine. To use data from QuantConnect Cloud, 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.

US Equity Options Algorithms

Follow these steps to run a local US Equity Options backtest:

1. Download the US Equity Security Master dataset.

   $ lean data download --dataset "US Equity Security Master"

2. Download minute resolution trade data from the US Equity 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 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.

   $ lean project-create --language python "<projectName>"

   You can use the following example algorithm:

If you have the latest version of LEAN and you get different overall statistics when you run the algorithm on your local machine versus in the cloud, delete your local data files and re-download them. 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:

When you run a backtest in QuantConnect Cloud, it uses the data from the Dataset Market. Follow these steps to run a cloud backtest:

1. Log in to the CLI if you haven't done so already.
2. Open a terminal in the organization workspace that contains the project you want to backtest.
3. Run lean cloud backtest "<projectName>" --push --open to push . / <projectName> 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.

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 file.

Follow these steps to use the ApiDataProvider to automatically download the data you need:

1. Log in to the CLI if you haven't done so already.
2. Open a terminal in the organization workspace that contains the project you want to backtest.
3. Run lean backtest "<projectName>" --download-data to run a local backtest for the project in . / <projectName> 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.
2. Run lean backtest "<projectName>" --data-provider-historical Local to run a local backtest for the project in . / <projectName> 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. 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 <value> option to set the QCC spending limit for the backtest.

All the options documented above are also available on the lean research command.

To get the Id of a local backtest, check the name of the <organizationWorkspace> / <projectName> / <deploymentTimestamp> / <backtestId>.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. An example cloud backtest Id is 8b16cec0c44f75188d82f9eadb310e17.