# Understanding `python.analysis.nodeExecutable` in Pylance

[Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) is a powerful language server extension for Python in Visual Studio Code, providing features such as auto-completion, type checking, and code navigation. It's built on top of Microsoft's open-source static type checking tool, Pyright.

When working with large Python projects, especially those with extensive dependencies or complex codebases, you might encounter out-of-memory errors due to the limitations of the default Node.js runtime bundled with VS Code.

To address this, Pylance offers the `python.analysis.nodeExecutable` setting. This guide explains what `python.analysis.nodeExecutable` does, why you might need to use it, and how to configure it in your development environment.

## What is `python.analysis.nodeExecutable`?

The `python.analysis.nodeExecutable` setting allows you to specify a custom path to a Node.js executable that Pylance will use instead of the default Node.js runtime bundled with Visual Studio Code. Alternatively, you can set the value to `"auto"`, allowing Pylance to automatically download and use the correct Node.js version.

This is particularly helpful for resolving out-of-memory issues, as the default Node.js runtime has a memory limit (typically around 4GB on 64-bit systems due to [pointer compression](https://www.electronjs.org/blog/v8-memory-cage)) that can cause Pylance to crash or underperform when analyzing large codebases.

## Configuring `python.analysis.nodeExecutable`

### Steps to Set Up `python.analysis.nodeExecutable`

- **Automatic Configuration**:

    To let Pylance automatically handle Node.js installation:

    ```json
    "python.analysis.nodeExecutable": "auto"
    ```

- **Manual Configuration**:
    1. **Install Node.js on Your System**:
        - Download and install the latest Node.js version from the [official website](https://nodejs.org/en/download/).
        - Ensure that the Node.js executable (`node` or `node.exe`) is accessible from your system path.

    2. **Locate the Path to the Node.js Executable**:
        - Find the absolute path to your Node.js executable. This may vary depending on your operating system and installation method.
            - **Windows Example**: `C:\Program Files\nodejs\node.exe`
            - **macOS/Linux Example**: `/usr/local/bin/node` or `/home/user/.nvm/versions/node/v18.16.0/bin/node`

    3. **Modify the **`python.analysis.nodeExecutable`** Setting in Visual Studio Code**:
        - **Open the Settings**:
            - Click on the gear icon in the lower-left corner and select **Settings**.

        - **Search for the Setting**:
            - In the search bar at the top, type `python.analysis.nodeExecutable`.

            - If you're using a remote environment (like SSH or WSL), make sure you're editing the remote settings.

        - **Set the Node.js Executable Path**:

            ```json
            "python.analysis.nodeExecutable": "/usr/local/bin/node"
            ```

    4. **Restart Visual Studio Code**:
        - Restart VS Code to apply the changes.

### Important Considerations

- **Security Warning (Manual Configuration)**:

    Be cautious when setting a manual path for the Node.js executable, especially in team environments or shared projects. Pylance will prompt for confirmation the first time you set this value, ensuring you trust the executable you're pointing to.

- **Scope of the Setting**:
    - The `python.analysis.nodeExecutable` setting is a _user-level_ setting.
    - It cannot be set in workspace or folder settings (`.vscode/settings.json`) to prevent security risks.

- **Remote Development Environments (Manual Configuration)** :
    - Ensure the Node.js executable path is valid on remote environments (like SSH, WSL, or Codespaces).

## When and Why to Use `python.analysis.nodeExecutable`

### Addressing Out-of-Memory Errors

When analyzing large codebases, Pylance might crash with errors like:

```
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
```

By specifying a custom Node.js executable or using the automatic setting, you can allocate more memory and resolve these issues.

## Frequently Asked Questions

### Q: How much memory does Pylance allocate for custom Node.js?

**A:** When using either a manually installed Node.js executable or the automatic setting (`"auto"`), Pylance sets Node.js to use 8GB of heap by default. You can adjust the heap size using the [`python.analysis.nodeArguments`](python_analysis_nodeArguments.md) setting — for example, `["--max-old-space-size=16384"]` for 16GB.

### Q: What's the difference between the default Node.js runtime and a custom or auto-downloaded Node.js executable?

The bundled Node.js runtime in Visual Studio Code has [pointer compression](https://www.electronjs.org/blog/v8-memory-cage) enabled, restricting the entire process to approximately 4GB of memory, even on 64-bit operating systems. In contrast, a custom or automatically downloaded Node.js executable can utilize up to 8GB per worker thread, allowing significantly more memory usage on 64-bit systems.

### Q: How does the `auto` setting work?

**A:** When set to `"auto"`, Pylance checks [https://nodejs.org/dist/](https://nodejs.org/dist/) to identify and download the correct Node.js version for your platform. It verifies the downloaded file's checksum, caches it locally, and uses this verified Node.js binary for analysis.

## See Also

- [How to Tune Pylance Performance](../howto/performance-tuning.md) — using a dedicated Node.js process for larger heap
- [How to Set Up Pylance for Remote Development](../howto/remote-development.md) — node executable paths in remote environments

---

_For more information on Pylance settings and customization, refer to the **[Pylance Settings and Customization](https://code.visualstudio.com/docs/python/settings-reference)** documentation._

---

_This document was generated with the assistance of AI and has been reviewed by humans for accuracy and completeness._
