API Reference

lean optimize


Optimize a project's parameters locally using Docker.

$ lean optimize [OPTIONS] PROJECT


Runs a local optimization in a Docker container using the quantconnect/lean Docker image. The logs of the optimizer are shown in real-time and the full results of the optimizer and all executed backtests are stored in the <project> / optimizations / <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 optimize. If it is a project directory, the CLI looks for a main.py or Main.cs file, assuming the first file it finds to contain the algorithm to optimize.

By default, an interactive wizard is shown letting you configure the optimizer. When --optimizer-config or --strategy is given, the command runs in non-interactive mode and doesn't prompt for input.

When the --optimizer-config <config file> option is given, the specified config file is used. This option must point to a file containing a full optimizer config (the algorithm-type-name, algorithm-language and algorithm-location properties may be omitted). See the Optimizer.Launcher / config.example.json file in the LEAN repository for an example optimizer configuration file, which also contains documentation on all the required properties.

When --strategy is given, the optimizer configuration is read from the command-line options. This means the --strategy, --target, --target-direction, and --parameter options become required. Additionally, you can also use --constraint to specify optimization constraints.

In non-interactive mode, the parameters can be configured using the --parameter option. This option takes the following values: the name of the parameter, its minimum value, its maximum value, and its step size. You can provide this option multiple times to configure multiple parameters.

In non-interactive mode, the constraints can be configured using the --constraint option. This option takes a "statistic operator value" string as value, where the statistic must be a path to a property in a backtest's output file, like "TotalPerformance.PortfolioStatistics.SharpeRatio". This statistic can also be shortened to "SharpeRatio" or "Sharpe Ratio", in which case the command automatically converts it to the longer version. The value must be a number and the operator must be <, >, <=, >=, ==, or ==. You can provide this option multiple times to configure multiple constraints.

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.

Example non-interactive usage:

$ lean optimize "My Project" \
    --strategy "Grid Search" \
    --target "Sharpe Ratio" \
    --target-direction "max" \
    --parameter my-first-parameter 1 10 0.5 \
    --parameter my-second-parameter 20 30 5 \
    --constraint "Drawdown < 0.5" \
    --constraint "Sharpe Ratio >= 1"

To estimate the cost of running an optimization job without actually running it, add the --estimate option to the command. You need to backtest the project at least once in order to estimate the cost of optimizing it.

To set the maximum number of concurrent backtests to run, use the --max-concurrent-backtests option.

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

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 optimizer if it doesn't exist locally yet or if you pass the --update flag.


The lean optimize command expects the following arguments:

<project>The path to the project directory or algorithm file to optimize.


The lean optimize command supports the following options:

--output <directory>Directory to store results in (defaults to PROJECT/optimizations/TIMESTAMP)
-d, --detachRun the optimization in a detached Docker container and return immediately
--optimizer-config <file>The optimizer configuration file that should be used
--strategy <enum: Grid Search|Euler Search>The optimization strategy to use
--target <string>The target statistic of the optimization
--target-direction <enum: min|max>Whether the target must be minimized or maximized
--parameter <<string> <float> <float> <float>>...The 'parameter min max step' pairs configuring the parameters to optimize
--constraint <string>The 'statistic operator value' pairs configuring the constraints of the optimization
--data-provider-historical <enum: Interactive Brokers
                                  Coinbase Advanced Trade
                                  Terminal Link
Update the Lean configuration file to retrieve data from the given historical provider
--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)
--updatePull the LEAN engine image before running the optimizer
--estimateEstimate optimization runtime without running it
--max-concurrent-backtests <integer> <range>[x>=1]
--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
--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
--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
--thetadata-rest-url <string>The ThetaData host address
--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
--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 optimize 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: