Editor setup

Editor setup#

After installing Isaac Lab, use the repository settings for VS Code or a compatible editor such as Cursor. Editor setup is optional.

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.

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

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

isaaclab --editor

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.

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 run python -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.

The generated launch configurations always run this recorded interpreter. VS Code resolves wrapper scripts such as _isaac_sim/python.sh to the underlying Python executable, which skips the environment setup that Isaac Sim requires. If .vscode/launch.json already exists, setup preserves it; add "python": "${config:python.defaultInterpreterPath}" to each configuration, or delete the file and rerun setup to regenerate it.

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.

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: