Editor setup

Editor setup is optional and is not required to run Isaac Lab. The repository includes shared settings for Visual Studio Code and compatible editors such as Cursor. Complete one of the Isaac Lab installation methods before configuring your editor.

The .vscode directory contains the checked-in templates and tasks:

.vscode
├── tools
│   ├── launch.template.json
│   └── settings.template.json
├── extensions.json
├── launch.json  # generated by isaaclab --editor
├── settings.json  # generated by isaaclab --editor
└── tasks.json

Configure a source checkout

Open the Isaac Lab repository root in your editor. Then run the setup command that matches your installation from a terminal in that directory.

uv (recommended)

For the default Newton environment, run:

uv run isaaclab --editor

If you use Isaac Sim from the isaacsim extra, include the extra so the setup command can discover its extensions:

uv run --extra isaacsim isaaclab --editor

Activated Python environment

Activate the uv, venv, or conda environment where Isaac Lab is installed, then run:

isaaclab --editor

Downloaded Isaac Sim package

Run the setup command through the Isaac Lab launcher after completing the downloaded package installation:

Linux

./isaaclab.sh --editor

Windows

isaaclab.bat --editor

The setup_python_env task in the command palette runs the recommended uv workflow.

The command creates or updates these machine-local files:

• .vscode/launch.json: Debugging configurations. An existing file is preserved.

• .vscode/settings.json: The interpreter and shared editor settings.

• pyrightconfig.json: Import paths for Pyright-compatible language servers.

The generated files are ignored by Git because interpreter and extension paths vary between machines. Rerun the command after changing Python environments or Isaac Sim installations. If Isaac Sim is not installed, the command prints a warning and still configures the local Isaac Lab packages.

The checked-in [tool.pyright] table in pyproject.toml makes packages under source available immediately after cloning. The generated pyrightconfig.json inherits that policy and adds Isaac Sim extensions plus Isaac Lab packages found in the active Python environment. This covers source, editable, and wheel installations without storing absolute paths in Git.

Configure VS Code

Install the extensions recommended by the repository when VS Code prompts you. At minimum, install the Python and Pylance extensions. Run the setup command above, then use Python: Select Interpreter from the command palette to select the same interpreter used by the command. For the recommended uv installation, this is .venv/bin/python on Linux or .venv\Scripts\python.exe on Windows.

Configure Cursor

Cursor cannot use Pylance because Pylance is licensed for official VS Code builds. Install the Python extension and the basedpyright extension (detachhead.basedpyright). Then:

1. Run the same setup command shown above for your installation.

2. Select the interpreter that ran the command.

3. Reload the Cursor window so basedpyright rereads pyrightconfig.json.

No Cursor-specific path list is required. Pylance and basedpyright read the same Pyright configuration.

Troubleshoot editor imports

If an import is still unresolved:

1. Confirm the selected editor interpreter matches python in the setup command.

2. Rerun setup with uv run --extra isaacsim isaaclab --editor if the missing import is from omni, pxr, or isaacsim.

3. Reload the editor window.

4. Inspect the generated extraPaths in the root pyrightconfig.json.

Remove simulator extension directories that the project does not use if language-server indexing consumes too much memory.

For more information about VS Code support in Isaac Sim, see:

• Isaac Sim VSCode support

Attach to a Running debugpy Session

The generated .vscode/launch.json includes a Python: Debugger Attach configuration that starts to listen on port localhost:3000 for the debugpy session.

To use it:

1. Set your breakpoints.

2. Run your code under debugpy like so:

   uv (Recommended)

   uv run python -m debugpy --listen 3000 --wait-for-client -c "from isaaclab.cli import cli; cli()" [cli_args]
   

   isaaclab.sh / isaaclab.bat

   ./isaaclab.sh -p -m debugpy --listen 3000 --wait-for-client -c "from isaaclab.cli import cli; cli()" [cli_args]
   

3. In VS Code, select the Python: Debugger Attach configuration from the Run and Debug panel and press the green play button or F5. VS Code will connect to the debugpy server running on localhost:3000.

Configuring the Python interpreter

The setup command records the interpreter that ran it in .vscode/settings.json. For example, a uv source checkout on Linux uses:

{
   "python.defaultInterpreterPath": "/path/to/IsaacLab/.venv/bin/python",
}

The editor selection takes precedence over this default. If you change environments, rerun setup and select the new interpreter from the status bar or with Python: Select Interpreter in the command palette.

For more information about selecting a Python interpreter, see the VS Code documentation.

Setting up formatting and linting

We use ruff as a formatter and linter. These are configured in the .vscode/settings.json file:

{
   "ruff.configuration": "${workspaceFolder}/pyproject.toml",
}

The ruff linter will show warnings and errors in your code to help you follow Python best practices and the project’s coding standards.