---
title: "Research"
description: "Learn how to run local research in different editors supported by Lean CLI."
canonical: https://www.quantconnect.com/docs/v2/lean-cli/research
markdown: https://www.quantconnect.com/docs/v2/lean-cli/research.md
language: python
source: https://github.com/QuantConnect/Documentation/tree/master/05%20Lean%20CLI/07%20Research
modified: 2026-10-29
index: https://www.quantconnect.com/llms.txt
---

# Research

[Documentation](https://www.quantconnect.com/docs/v2.md) > [Lean CLI](https://www.quantconnect.com/docs/v2/lean-cli.md) > Research

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

## Introduction

Starting local Jupyter Lab environments is a powerful feature of the Lean CLI. Jupyter Lab environments allow you to work on research notebooks locally. These environments contain the same features as [QuantConnect's research environment](https://www.quantconnect.com/docs/v2/research-environment.md) but run on your local machine.

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.

To use data in local research notebooks, you must have the data on your machine. To get local data, use 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).

## Start the Research Environment

You can run the Research Environment with your current configuration or an old configuration from QuantConnect.

### Current Configuration

The default Research Environment configuration is the latest master branch of LEAN. If you [set a different research image](https://www.quantconnect.com/docs/v2/lean-cli/projects/custom-docker-images.md#02-Using-Custom-Images), the image you set is your current configuration. To start a local research environment with your current configuration, open a terminal in one of your [organization workspaces](https://www.quantconnect.com/docs/v2/lean-cli/initialization/organization-workspaces.md) and then run `lean research "<projectName>"` to start a local research environment for the project in `. / <projectName>` on port `8888`.

```
$ lean research "My Project"
Starting JupyterLab, access in your browser at localhost:8888
```

JupyterLab automatically opens in your default browser. If you intend to use PyCharm or VS Code instead of JupyterLab, include the `--no-open` option to not open JupyterLab. To run the environment on a different port by providing the `--port <port>` option.

If your configuration is set to the master branch of LEAN, the CLI automatically checks if your image is behind master every seven days. If your image falls behind master, the CLI automatically updates your image to the lastest version. To force an update before the automatic check, add the `--update` option. To avoid updates, add the `--no-update` option.

### Old Configurations from QuantConnect

Follow these steps to start a local Research Environment with an old research configuration from QuantConnect:

1. View the available versions on the [quantconnect/research Docker Hub tags page](https://hub.docker.com/r/quantconnect/research/tags).
2. Copy the name of the tag you want to run.
3. Open a terminal in one of your [organization workspaces](https://www.quantconnect.com/docs/v2/lean-cli/initialization/organization-workspaces.md).
4. Run `lean research "<projectName>" --image quantconnect/research:<tagFromStep2>` to start a local Research Environment for the project in `. / <projectName>`.

   ```
   $ lean research "My Project" --image quantconnect/research:11154
   Pulling quantconnect/research: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 the Research Environment, 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](https://www.quantconnect.com/docs/v2/lean-cli/api-reference/lean-research.md).

## Use JypterLab

The following sections explain how to operate the Research Environment with [JupyterLab](https://jupyterlab.readthedocs.io/en/latest/index.html), the default IDE.

### Open Notebooks

Follow these steps to open a research notebook in JupyterLab:

1. [Start a local research environment](https://www.quantconnect.com/docs/v2/lean-cli/research.md#02-Start-the-Research-Environment) for the project that contains the notebook.
2. In the left navigation menu, click the ![JupyterLab File Browser icon](https://cdn.quantconnect.com/i/tu/jupyterlab-file-browser-icon.png) **File Browser** icon.
3. In the File Browser panel, double-click the notebook file you want to open.
   The default notebook is `research.ipynb`.
   ![Open notebooks with JupyterLab](https://cdn.quantconnect.com/i/tu/jupyterlab-open-notebooks.png)

For more information about opening files in JupyterLab, see [Opening Files](https://jupyterlab.readthedocs.io/en/latest/user/files.html#opening-files) in the JupyterLab documentation.

### Run Notebook Cells

Notebooks are a collection of cells where you can write code snippets or MarkDown. To execute a cell, press **Shift+Enter**.

![Python jupyter notebook interface](https://cdn.quantconnect.com/i/tu/notebook-cells-py.jpg)

The following describes some helpful keyboard shortcuts to speed up your research:

| Keyboard Shortcut | Description |
| --- | --- |
| **Shift+Enter** | Run the selected cell. |
| **a** | Insert a cell above the selected cell. |
| **b** | Insert a cell below the selected cell. |
| **x** | Cut the selected cell. |
| **v** | Paste the copied or cut cell. |
| **z** | Undo cell actions. |

For more information about keyboard shortcuts in JupyterLab, see [Keyboard Shortcuts](https://jupyterlab.readthedocs.io/en/latest/user/interface.html#keyboard-shortcuts) in the JupyterLab documentation.

### Stop Nodes

Follow these steps to stop a research node in JupyterLab:

1. In the left navigation menu, click the ![JupyterLab Running Terminals and Kernals icon](https://cdn.quantconnect.com/i/tu/jupyterlab-running-terminals-and-kernals-icon.png) **Running Terminals and Kernels** icon.
2. In the **Kernals** section of the Running Terminals and Kernels panel, right-click the name of the notebook file and then click **Shut Down Kernel** from the drop-down menu.

![Stop notebooks with JupyterLab](https://cdn.quantconnect.com/i/tu/jupyterlab-stop-nodes.png)

For more information about the Running Terminals and Kernels panel in JupyterLab, see [Managing Kernels and Terminals](https://jupyterlab.readthedocs.io/en/latest/user/running.html) in the JupyterLab documentation.

### Add Notebooks

Follow these steps to add notebook files to a project in JupyterLab:

1. [Start a local research environment](https://www.quantconnect.com/docs/v2/lean-cli/research.md#02-Start-the-Research-Environment) for the project.
2. In the top navigation menu, click **File > New > Notebook**.
3. In the Select Kernel window, click **Select**.

For more information about the creating files in JupyterLab, see [Creating Files and Activities](https://jupyterlab.readthedocs.io/en/latest/user/files.html#creating-files-and-activities) in the JupyterLab documentation.

### Rename Notebooks

Follow these steps to rename notebook files in JupyterLab:

1. [Start a local research environment](https://www.quantconnect.com/docs/v2/lean-cli/research.md#02-Start-the-Research-Environment) for the project that contains the notebook.
2. In the left navigation menu, click the ![JupyterLab File Browser icon](https://cdn.quantconnect.com/i/tu/jupyterlab-file-browser-icon.png) **File Browser** icon.
3. In the File Browser panel, right-click the notebook file you want to rename and then click **Rename** from the drop-down menu.
4. Enter the new name.
5. Press **Enter**.

### Delete Notebooks

Follow these steps to delete notebook files in JupyterLab:

1. [Start a local research environment](https://www.quantconnect.com/docs/v2/lean-cli/research.md#02-Start-the-Research-Environment) for the project that contains the notebook.
2. In the left navigation menu, click the ![JupyterLab File Browser icon](https://cdn.quantconnect.com/i/tu/jupyterlab-file-browser-icon.png) **File Browser** icon.
3. In the File Browser panel, right-click the notebook file you want to delete and then click **Delete** from the drop-down menu.
4. In the Delete window, click **Delete**.

## Use PyCharm

The following sections explain how to operate the Research Environment with [PyCharm](https://www.jetbrains.com/pycharm/).

### Open Notebooks

Follow these steps to open a research notebook in PyCharm:

1. [Start a local research environment](https://www.quantconnect.com/docs/v2/lean-cli/research.md#02-Start-the-Research-Environment) for the project that contains the notebook.
2. Open the same project in PyCharm.
3. In the top navigation menu of PyCharm, click **File > Settings**.
4. In the Settings window, click **Language & Frameworks > Jupyter > Jupyter Servers**.
5. Click **Configured Server**.
6. Enter **http://localhost:8888/?token=** into the field.
7. Click **Apply** to save the changes.
8. Click **OK** to exit the window.
9. In the left navigation menu, click the ![PyCharm Project icon](https://cdn.quantconnect.com/i/tu/pycharm-project-icon.png) **Project** icon.
10. In the Project panel, double-click the notebook file you want to open.
   The default notebook is `research.ipynb`.

### Run Notebook Cells

Notebooks are a collection of cells where you can write code snippets or MarkDown. To execute a cell, press **Shift+Enter**.

![Python jupyter notebook interface](https://cdn.quantconnect.com/i/tu/notebook-cells-py.jpg)

The following describes some helpful keyboard shortcuts to speed up your research:

| Keyboard Shortcut | Description |
| --- | --- |
| **Shift+Enter** | Run the selected cell. |
| **a** | Insert a cell above the selected cell. |
| **b** | Insert a cell below the selected cell. |
| **x** | Cut the selected cell. |
| **v** | Paste the copied or cut cell. |
| **z** | Undo cell actions. |

For more information about keyboard shortcuts in PyCharm, see [Keyboard Shortcuts](https://www.jetbrains.com/help/pycharm/mastering-keyboard-shortcuts.html) in the PyCharm documentation.

### Stop Nodes

Follow these steps to stop a research node in PyCharm:

1. In the left navigation menu, click the ![PyCharm Project icon](https://cdn.quantconnect.com/i/tu/pycharm-project-icon.png) **Project** icon.
2. In the Project panel, right-click the name of the notebook file and then click **Shutdown Kernel** from the drop-down menu.

For more information about the Jupyter notebook servers in PyCharm, see [Manage Jupyter notebook servers](https://www.jetbrains.com/help/pycharm/configuring-jupyter-notebook.html) in the PyCharm documentation.

### Add Notebooks

To add notebook files to a project in PyCharm, see [Create a notebook file](https://www.jetbrains.com/help/pycharm/editing-jupyter-notebook-files.html#create-notebook-file) in the PyCharm documentation.

### Rename Notebooks

Follow these steps to rename notebook files in PyCharm:

1. [Start a local research environment](https://www.quantconnect.com/docs/v2/lean-cli/research.md#02-Start-the-Research-Environment) for the project in PyCharm.
2. In the left navigation menu, click the ![PyCharm Project icon](https://cdn.quantconnect.com/i/tu/pycharm-project-icon.png) **Project** icon.
3. In the Project panel, right-click the notebook file you want to rename and then click **Refactor > Rename** from the drop-down menu.
4. Enter the new name.
5. Press **Enter**.

### Delete Notebooks

Follow these steps to delete notebook files in PyCharm:

1. [Start a local research environment](https://www.quantconnect.com/docs/v2/lean-cli/research.md#02-Start-the-Research-Environment) for the project in PyCharm.
2. In the left navigation menu, click the ![PyCharm Project icon](https://cdn.quantconnect.com/i/tu/pycharm-project-icon.png) **Project** icon.
3. In the Project panel, right-click the notebook file you want to rename and then click **Delete** from the drop-down menu.
4. In the Delete window, click **OK**.

## Use VS Code

The following sections explain how to operate the Research Environment with VS Code.

### Open Notebooks

Follow these steps to open a research notebook in VS Code:

1. [Start a local research environment](https://www.quantconnect.com/docs/v2/lean-cli/research.md#02-Start-the-Research-Environment) for the project that contains the notebook.
2. Open the same project VS Code.
3. In the Explore panel, click the notebook file you want to open.
   The default notebook is `research.ipynb`.
4. In the top-right corner of the notebook, click **Select Kernel**.
5. In the Select Another Kernel window, click **Existing Jypter Server...**.
6. Enter **http://localhost:8888/** into the field.
7. Press **Enter**.
8. (Optional) Enter a display name for the server and then press **Enter**.
9. Click **Foundation-Py-Default**.

### Run Notebook Cells

Notebooks are a collection of cells where you can write code snippets or MarkDown. To execute a cell, press **Shift+Enter**.

![Python jupyter notebook interface](https://cdn.quantconnect.com/i/tu/notebook-cells-py.jpg)

The following describes some helpful keyboard shortcuts to speed up your research:

| Keyboard Shortcut | Description |
| --- | --- |
| **Shift+Enter** | Run the selected cell. |
| **a** | Insert a cell above the selected cell. |
| **b** | Insert a cell below the selected cell. |
| **x** | Cut the selected cell. |
| **v** | Paste the copied or cut cell. |
| **z** | Undo cell actions. |

For more information about keyboard shortcuts in VS Code, see [Key Bindings for Visual Studio Code](https://code.visualstudio.com/docs/getstarted/keybindings) in the VS Code documentation.

### Add Notebooks

Follow these steps to add notebook files to a project in VS Code:

1. [Open the project](https://www.quantconnect.com/docs/v2/local-platform/projects/getting-started.md#04-Open-Projects).
2. In the right navigation menu, click the ![Local lab explorer icon](https://cdn.quantconnect.com/i/tu/local-lab-explorer-icon.jpg) **Explorer** icon.
3. In the Explorer panel, expand the **QC (Workspace)** section.
4. Click the ![Add new file icon](https://cdn.quantconnect.com/i/tu/new-file-icon.png) **New File** icon.
5. Enter `fileName .ipynb`.
6. Press **Enter**.

### Rename Notebooks

Follow these steps to rename notebook files in VS Code:

1. [Start a local research environment](https://www.quantconnect.com/docs/v2/lean-cli/research.md#02-Start-the-Research-Environment) for the project that contains the notebook.
2. In the right navigation menu, click the ![Local lab explorer icon](https://cdn.quantconnect.com/i/tu/local-lab-explorer-icon.jpg) **Explorer** icon.
3. In the Explorer panel, expand the **QC (Workspace)** section.
4. Click the ![Add new file icon](https://cdn.quantconnect.com/i/tu/new-file-icon.png) **New File** icon.
5. Enter `fileName .ipynb`.
6. Press **Enter**.

### Delete Notebooks

Follow these steps to delete notebook files in VS Code:

1. [Start a local research environment](https://www.quantconnect.com/docs/v2/lean-cli/research.md#02-Start-the-Research-Environment) for the project that contains the notebook.
2. In the right navigation menu, click the ![Local lab explorer icon](https://cdn.quantconnect.com/i/tu/local-lab-explorer-icon.jpg) **Explorer** icon.
3. In the Explorer panel, right-click the notebook you want to rename and then click **Rename**.
4. Enter the new name and then press **Enter**.

## Retrieving Local Backtests

Sometimes it might be useful to retrieve the results of a previously ran local backtest in the research environment. By default, backtests are saved in the `<projectName> / backtests / <timestamp>` directory, which is also available in the research environment. You can use the following code snippet to read the contents of a backtest's result file into a local variable and to print its statistics (make sure to replace the path to the backtest with your own):

```python
import json

backtest_path = "backtests/2021-03-03_01-57-38/main.json"

with open(backtest_path) as file:
    data = json.load(file)

for key, value in data["Statistics"].items():
    print(f"{key}: {value}")
```

## Retrieving Cloud Backtests

If you are [logged in](https://www.quantconnect.com/docs/v2/lean-cli/initialization/authentication.md#02-Log-In) using `lean login` you can also retrieve cloud backtest results in your local research environment. If you know the name of the project and the backtest you can use the following code snippet to retrieve the backtest's results and to print its statistics:

```python
project_name = "Python Template"
backtest_name = "Adaptable Tan Frog"

project = next(p for p in api.list_projects().projects if p.name == project_name)
partial_backtest = next(b for b in api.list_backtests(project.project_id).backtests if b.name == backtest_name)
backtest = api.read_backtest(project.project_id, partial_backtest.backtest_id)

for key in backtest.statistics.keys:
    print(f"{key}: {backtest.statistics[key]}")
```