API Reference

lean research


Run a Jupyter Lab environment locally using Docker.

$ lean research <project> [options]


Runs a local Jupyter Lab environment in a Docker container using the quantconnect/research Docker image. The project directory is mounted in the Docker container and the Jupyter Lab instance is exposed on a local port. After the Jupyter Lab instance has started, the browser automatically opens.

By default, Jupyter Lab is exposed on port 8888. To use a custom port, you can use the --port option, which is required to run two Jupyter Lab instances side-by-side.

You can use the --data-provider-historical option to change where 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. If you use the 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 and the --data-purchase-limit option to set the maximum amount of QuantConnect Credit (QCC) to spend during the research session when using QuantConnect as data provider. The --data-purchase-limit option is not persistent.

If you have previously logged in using lean login, the CLI automatically makes your credentials available in the Jupyter Lab instance. If this happens, the api variable is automatically assigned an instance of Api in your research notebooks, which you can use to make authenticated requests to the QuantConnect API.

The default Research Environment configuration is the latest master branch of LEAN. If you set a different research image, the image you set is your current configuration. To start the Research Environment with a different configuration than your current configuration, use the --image <value> option. If the image doesn't exist on your local machine or you pass the --update flag, the image is pulled before starting the Research Environment. To avoid updating the image, pass the --no-update flag.


The lean research command expects the following arguments:

<project>The path to the project directory for which to run a research environment.


The lean research command supports the following options:

--port <value>The port to run Jupyter Lab on (defaults to 8888).
--data-provider-historicalThe historical data source.
--iqfeed-iqconnect <path>The path to your IQConnect binary.
--iqfeed-username <value>Your IQFeed username.
--iqfeed-password <value>Your IQFeed password.
--iqfeed-version <value>The product version of your IQFeed developer account.
--iqfeed-hostThe IQFeed host address.
--polygon-api-key <value>Your Polygon.io API Key
--iex-cloud-api-keyYour IEX Cloud API Key.
--iex-price-planYour IEX Cloud price plan. Launch, Grow, or Enterprise.
--alpha-vantage-api-keyYour Alpha Vantage API Key.
--alpha-vantage-price-planYour Alpha Vantage price plan. Free, Plan30, Plan75, Plan150, Plan300, Plan600, or Plan1200.
--terminal-link-connection-type <value>The Terminal Link connection type, which must be SAPI or DAPI.
--terminal-link-server-auth-id <value>Your unique user identifier (UUID). The UUID is a unique integer identifier that's assigned to each Bloomberg Anywhere user. If you don't know your UUID, contact Bloomberg.
--terminal-link-environment <value>The environment to run in, which must be Production or Beta.
--terminal-link-server-host <value>The host on which the Terminal Link server is running.
--terminal-link-server-port <value>The port on which the Terminal Link server is running.
--terminal-link-openfigi-api-key <value>The OpenFIGI API key to use for mapping Options.
--download-dataUpdate the Lean configuration file to download data from the QuantConnect API, alias for --data-provider-historical QuantConnect.
--data-purchase-limit <value>The maximum amount of QCC to spend on downloading data during the research session when using QuantConnect as data provider.
--detach, -dRun Jupyter Lab in a detached Docker container and return immediately. The name of the Docker container is shown before the command ends. You can use Docker's own commands to manage the detached container.
--no-openDon't open the Jupyter Lab environment in the browser after starting it.
--image <value>The LEAN research image to use (defaults to quantconnect/research:latest).
--updatePull the LEAN research image before starting the research environment.
--no-updateUse the current LEAN research image.
--lean-config <path>The Lean configuration file that should be used (defaults to the nearest lean.json file).
--verboseEnable debug logging.
--helpDisplay the help text of the lean research 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: