.. _setup-vs-code:

Editor setup
------------

Editor setup is optional and is not required to run Isaac Lab. The repository
includes shared settings for `Visual Studio Code <https://code.visualstudio.com/>`_
and compatible editors such as `Cursor <https://www.cursor.com/>`_. Complete one
of the :ref:`Isaac Lab installation methods <isaaclab-installation-root>` before
configuring your editor.

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

.. code-block:: bash

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

.. tab-set::

   .. tab-item:: uv (recommended)

      For the default Newton environment, run:

      .. code-block:: bash

         uv run isaaclab --editor

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

      .. code-block:: bash

         uv run --extra isaacsim isaaclab --editor

   .. tab-item:: Activated Python environment

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

      .. code-block:: bash

         isaaclab --editor

   .. tab-item:: Downloaded Isaac Sim package

      Run the setup command through the Isaac Lab launcher after completing the
      :ref:`downloaded package installation <isaaclab-binaries-installation>`:

      .. tab-set::
         :sync-group: os

         .. tab-item:: :icon:`fa-brands fa-linux` Linux
            :sync: linux

            .. code-block:: bash

               ./isaaclab.sh --editor

         .. tab-item:: :icon:`fa-brands fa-windows` Windows
            :sync: windows

            .. code-block:: batch

               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
<https://marketplace.visualstudio.com/items?itemName=detachhead.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 <https://docs.isaacsim.omniverse.nvidia.com/latest/development_tools/vscode.html#visual-studio-code-vs-code>`__


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:

   .. tab-set::

      .. tab-item:: uv (Recommended)

         .. code-block:: bash

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

      .. tab-item:: isaaclab.sh / isaaclab.bat

         .. code-block:: bash

            ./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:

.. code-block:: json

   {
      "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 <https://code.visualstudio.com/docs/python/environments#_working-with-python-interpreters>`_.


Setting up formatting and linting
---------------------------------

We use `ruff <https://github.com/astral-sh/ruff/>`_ as a formatter and linter.
These are configured in the ``.vscode/settings.json`` file:

.. code-block:: json

   {
      "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.