Skip to content

Commit cb3f41e

Browse files
StafaHStafaH
committed
Clarify editor setup across installation workflows
1 parent ef26b90 commit cb3f41e

4 files changed

Lines changed: 146 additions & 50 deletions

File tree

‎docs/source/developer-tools/template_generator.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -259,6 +259,11 @@ the configuration:
259259
260260
uv run --extra isaacsim python .vscode/tools/setup_vscode.py
261261
262+
In VS Code, use Pylance and select the interpreter that ran the setup command.
263+
In Cursor, install the ``detachhead.basedpyright`` extension instead of Pylance,
264+
select the same interpreter, and reload the window. Both language servers read
265+
the generated ``pyrightconfig.json``.
266+
262267
Create an internal task
263268
-----------------------
264269

‎docs/source/overview/developer-guide/vs_code.rst‎

Lines changed: 117 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
11
.. _setup-vs-code:
22

3-
Setting up Visual Studio Code
4-
-----------------------------
3+
Setting up VS Code or Cursor
4+
----------------------------
55

6-
**This is optional. You do not need to use VScode to use Isaac Lab**
6+
Editor setup is optional and is not required to run Isaac Lab. The repository
7+
includes shared settings for `Visual Studio Code <https://code.visualstudio.com/>`_
8+
and compatible editors such as `Cursor <https://www.cursor.com/>`_. Complete one
9+
of the :ref:`Isaac Lab installation methods <isaaclab-installation-root>` before
10+
configuring your editor.
711

8-
`Visual Studio Code <https://code.visualstudio.com/>`_ has proven an invaluable tool for the development of Isaac Lab. The Isaac Lab repository includes the VSCode files for setting up your development environment. These are included in the ``.vscode`` directory and include the following files:
12+
The ``.vscode`` directory contains the checked-in templates and tasks:
913

1014
.. code-block:: bash
1115
@@ -15,58 +19,123 @@ Setting up Visual Studio Code
1519
│   ├── settings.template.json
1620
│   └── setup_vscode.py
1721
├── extensions.json
18-
├── launch.json # <- this is generated by setup_vscode.py
19-
├── settings.json # <- this is generated by setup_vscode.py
22+
├── launch.json # generated by setup_vscode.py
23+
├── settings.json # generated by setup_vscode.py
2024
└── tasks.json
2125
26+
Configure a source checkout
27+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
2228

23-
.. attention::
29+
Open the Isaac Lab repository root in your editor. Then run the setup command
30+
that matches your installation from a terminal in that directory.
2431

25-
The following instructions on setting up Visual Studio Code only work with
26-
:ref:`Isaac Sim Binaries Installation <isaaclab-binaries-installation>` and not with
27-
:ref:`Python Environment with Isaac Sim <installation-method-python-env>`.
32+
.. tab-set::
2833

34+
.. tab-item:: uv (recommended)
2935

30-
To setup the IDE, please follow these instructions:
36+
For the default Newton environment, run:
3137

32-
1. Open the ``IsaacLab`` directory on Visual Studio Code IDE
33-
2. Run VSCode `Tasks <https://code.visualstudio.com/docs/editor/tasks>`__, by
34-
pressing ``Ctrl+Shift+P``, selecting ``Tasks: Run Task`` and running the
35-
``setup_python_env`` in the drop down menu.
38+
.. code-block:: bash
3639
37-
.. image:: ../../_static/vscode_tasks.png
38-
:width: 600px
39-
:align: center
40-
:alt: VSCode Tasks
40+
uv run python .vscode/tools/setup_vscode.py
4141
42+
If you use Isaac Sim from the ``isaacsim`` extra, include the extra so the
43+
setup command can discover its extensions:
4244

43-
.. note::
44-
If this is your first time running tasks in VS Code, you may be prompted to select how to handle warnings. Simply follow
45-
the prompts until the task window closes.
45+
.. code-block:: bash
4646
47-
If everything executes correctly, it should create the following files:
47+
uv run --extra isaacsim python .vscode/tools/setup_vscode.py
4848
49-
* ``.vscode/launch.json``: Contains the launch configurations for debugging python code.
50-
* ``.vscode/settings.json``: Contains the settings for the python interpreter and the python environment.
51-
* ``pyrightconfig.json``: Contains machine-local import paths for Pyright-compatible language servers.
49+
.. tab-item:: Activated Python environment
5250

53-
.. note::
51+
Activate the uv, venv, or conda environment where Isaac Lab is installed,
52+
then run:
5453

55-
Type information for the in-repository Isaac Lab packages (``isaaclab``, ``isaaclab_tasks``, ...)
56-
works before running this task because their source roots are registered in ``pyproject.toml``.
57-
The task generates a git-ignored ``pyrightconfig.json`` that inherits those settings and adds the
58-
Isaac Sim extensions (``omni.*``, ``pxr.*``, ``isaacsim.*``) plus Isaac Lab packages discovered
59-
in the active Python environment. This also supports editable and wheel installations.
54+
.. code-block:: bash
6055
61-
.. note::
56+
python .vscode/tools/setup_vscode.py
6257
63-
**Using Cursor?** Cursor cannot run Pylance (it is licensed for official VS Code builds only), so
64-
install the `basedpyright <https://marketplace.visualstudio.com/items?itemName=detachhead.basedpyright>`__
65-
extension (``detachhead.basedpyright``) as the language server. It reads the same Pyright
66-
configuration, so Isaac Lab type information works there without any extra setup.
58+
.. tab-item:: Downloaded Isaac Sim package
6759

68-
For more information on VSCode support for Omniverse, please refer to the
69-
following links:
60+
Run the setup script through the Isaac Lab launcher after completing the
61+
:ref:`downloaded package installation <isaaclab-binaries-installation>`:
62+
63+
.. tab-set::
64+
:sync-group: os
65+
66+
.. tab-item:: :icon:`fa-brands fa-linux` Linux
67+
:sync: linux
68+
69+
.. code-block:: bash
70+
71+
./isaaclab.sh -p .vscode/tools/setup_vscode.py
72+
73+
.. tab-item:: :icon:`fa-brands fa-windows` Windows
74+
:sync: windows
75+
76+
.. code-block:: batch
77+
78+
isaaclab.bat -p .vscode\tools\setup_vscode.py
79+
80+
The ``setup_python_env`` task in the command palette runs the same launcher
81+
workflow for a downloaded package.
82+
83+
The command creates or updates these machine-local files:
84+
85+
* ``.vscode/launch.json``: Debugging configurations. An existing file is preserved.
86+
* ``.vscode/settings.json``: The interpreter and shared editor settings.
87+
* ``pyrightconfig.json``: Import paths for Pyright-compatible language servers.
88+
89+
The generated files are ignored by Git because interpreter and extension paths
90+
vary between machines. Rerun the command after changing Python environments or
91+
Isaac Sim installations. If Isaac Sim is not installed, the command prints a
92+
warning and still configures the local Isaac Lab packages.
93+
94+
The checked-in ``[tool.pyright]`` table in ``pyproject.toml`` makes packages
95+
under ``source`` available immediately after cloning. The generated
96+
``pyrightconfig.json`` inherits that policy and adds Isaac Sim extensions plus
97+
Isaac Lab packages found in the active Python environment. This covers source,
98+
editable, and wheel installations without storing absolute paths in Git.
99+
100+
Configure VS Code
101+
^^^^^^^^^^^^^^^^^
102+
103+
Install the extensions recommended by the repository when VS Code prompts you.
104+
At minimum, install the Python and Pylance extensions. Run the setup command
105+
above, then use **Python: Select Interpreter** from the command palette to select
106+
the same interpreter used by the command. For the recommended uv installation,
107+
this is ``.venv/bin/python`` on Linux or ``.venv\Scripts\python.exe`` on Windows.
108+
109+
Configure Cursor
110+
^^^^^^^^^^^^^^^^
111+
112+
Cursor cannot use Pylance because Pylance is licensed for official VS Code
113+
builds. Install the Python extension and the `basedpyright
114+
<https://marketplace.visualstudio.com/items?itemName=detachhead.basedpyright>`__
115+
extension (``detachhead.basedpyright``). Then:
116+
117+
1. Run the same setup command shown above for your installation.
118+
2. Select the interpreter that ran the command.
119+
3. Reload the Cursor window so basedpyright rereads ``pyrightconfig.json``.
120+
121+
No Cursor-specific path list is required. Pylance and basedpyright read the
122+
same Pyright configuration.
123+
124+
Troubleshoot editor imports
125+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
126+
127+
If an import is still unresolved:
128+
129+
1. Confirm the selected editor interpreter matches ``python`` in the setup command.
130+
2. Rerun setup with ``--extra isaacsim`` if the missing import is from
131+
``omni``, ``pxr``, or ``isaacsim``.
132+
3. Reload the editor window.
133+
4. Inspect the generated ``extraPaths`` in the root ``pyrightconfig.json``.
134+
135+
Remove simulator extension directories that the project does not use if
136+
language-server indexing consumes too much memory.
137+
138+
For more information about VS Code support in Isaac Sim, see:
70139

71140
* `Isaac Sim VSCode support <https://docs.isaacsim.omniverse.nvidia.com/latest/development_tools/vscode.html#visual-studio-code-vs-code>`__
72141

@@ -100,26 +169,24 @@ To use it:
100169
and press the green play button or ``F5``. VS Code will connect to the debugpy server
101170
running on ``localhost:3000``.
102171

103-
Configuring the python interpreter
172+
Configuring the Python interpreter
104173
----------------------------------
105174

106-
In the provided configuration, we set the default python interpreter to use the
107-
python executable provided by Omniverse. This is specified in the
108-
``.vscode/settings.json`` file:
175+
The setup command records the interpreter that ran it in
176+
``.vscode/settings.json``. For example, a uv source checkout on Linux uses:
109177

110178
.. code-block:: json
111179
112180
{
113-
"python.defaultInterpreterPath": "${workspaceFolder}/_isaac_sim/python.sh",
181+
"python.defaultInterpreterPath": "/path/to/IsaacLab/.venv/bin/python",
114182
}
115183
116-
If you want to use a different python interpreter (for instance, from your conda or uv environment),
117-
you need to change the python interpreter used by selecting and activating the python interpreter
118-
of your choice in the bottom left corner of VSCode, or opening the command palette (``Ctrl+Shift+P``)
119-
and selecting ``Python: Select Interpreter``.
184+
The editor selection takes precedence over this default. If you change
185+
environments, rerun setup and select the new interpreter from the status bar or
186+
with **Python: Select Interpreter** in the command palette.
120187

121-
For more information on how to set python interpreter for VSCode, please
122-
refer to the `VSCode documentation <https://code.visualstudio.com/docs/python/environments#_working-with-python-interpreters>`_.
188+
For more information about selecting a Python interpreter, see the
189+
`VS Code documentation <https://code.visualstudio.com/docs/python/environments#_working-with-python-interpreters>`_.
123190

124191

125192
Setting up formatting and linting

‎docs/source/setup/quickstart.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,26 @@ Training outputs, including checkpoints, are saved under ``logs/``. Add
3636
3737
uv run isaaclab train --help
3838
39+
Configure an editor (optional)
40+
------------------------------
41+
42+
To enable import completion and debugging in VS Code or Cursor, generate the
43+
machine-local editor configuration from the repository root:
44+
45+
.. code-block:: bash
46+
47+
uv run python .vscode/tools/setup_vscode.py
48+
49+
If you use the ``isaacsim`` extra, include it so the command can discover the
50+
Isaac Sim extensions:
51+
52+
.. code-block:: bash
53+
54+
uv run --extra isaacsim python .vscode/tools/setup_vscode.py
55+
56+
VS Code uses Pylance. Cursor users should install basedpyright instead. See
57+
:ref:`setup-vs-code` for complete editor and troubleshooting instructions.
58+
3959
.. The quickstart media is generated by tools/docs/media/generate_quickstart.sh.
4060
4161
.. figure:: https://download.isaacsim.omniverse.nvidia.com/isaaclab/images/quickstart_task_categories.gif

‎tools/template/templates/external/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,10 @@ configuration inherits the project's checked-in Pyright settings and adds the Is
8686
and any Isaac Lab packages discovered in the active Python environment. This supports both Pylance in VS Code and
8787
basedpyright in Cursor.
8888

89+
In VS Code, use Pylance and select the interpreter that ran the setup command. In Cursor, install the
90+
[basedpyright extension](https://marketplace.visualstudio.com/items?itemName=detachhead.basedpyright) instead of
91+
Pylance, select the same interpreter, and reload the window. Both language servers read `pyrightconfig.json`.
92+
8993
When using the `isaacsim` extra, include it while generating the editor configuration so the command can discover the
9094
Isaac Sim installation:
9195

0 commit comments

Comments
 (0)