PyCharm Setup#

Tips and configuration for developing with PyCharm. The committed .idea/ and .run/ files give you source roots, run/debug configurations, code style, file templates, and more out of the box — most setup is automatic when you open the project.

PyCharm Professional is required for debugging (remote debug server). Community edition works for editing and running the app, but cannot attach to the debug server.

Initial Setup#

1. Build the project#

Build first — the build populates _build/ with the Kit SDK, embedded Python interpreter, and all Omniverse extensions. It also generates .idea/lightspeed-kit.iml from .idea/lightspeed-kit.iml.template (via tools/utils/update_pycharm_sources.py) with:

  • Extension source roots — every directory under source/extensions/ for cross-extension imports

  • Build extra-paths — Kit kernel, extension cache, and pip bundle directories from _build/ (read from .vscode/settings.json python.analysis.extraPaths) grouped by container directory (extscache, extscore) so SDK imports (carb, pxr, omni.usd, etc.) resolve without manual interpreter-path configuration

  • Pip prebundle paths — discovered dynamically from deps/*.toml files that define [[dependency]] sections; the script reads each target field and finds the matching directories inside build extension directories so that third-party pip packages (pygit2, requests, py7zr, etc.) resolve correctly

The generated .iml is git-ignored; only the template is committed.

.\build.bat

2. Open the project#

Open the repo root in PyCharm. The committed .idea/ files automatically configure:

  • Source roots — every extension in source/extensions/ plus all _build/ SDK paths are registered as source roots for import resolution (generated by the build via tools/utils/update_pycharm_sources.py)

  • Excluded directories — _build, _compiler, _repo, _testoutput, rtx-remix excluded from indexing

  • Search scopes — “Source Extensions” and “Python Extensions” for focused searching (.idea/scopes/)

  • File types — .kit files recognized as TOML for syntax highlighting (.idea/fileTypes.xml)

  • File templates — new Python files include the SPDX Apache-2.0 license header; new unit tests scaffold an AsyncTestCase class (.idea/fileTemplates/)

  • Ruff — linting enabled project-wide (.idea/misc.xml)

  • Encoding — UTF-8 default (.idea/encodings.xml)

  • Required plugins — PyCharm will prompt to install TOML and Shell Script plugins if missing ( .idea/externalDependencies.xml)

  • Module structure — project module mapping (.idea/modules.xml)

3. Set file template scheme to Project#

The committed file templates (license header, unit test scaffold) only work when the template scheme is set to Project:

Settings (Ctrl+Alt+S) > Editor > File and Code Templates — set the Scheme dropdown (top of the page) to Project.

4. Configure the Python interpreter#

Point PyCharm to Kit’s embedded Python 3.10:

Settings (Ctrl+Alt+S) > Python > Interpreter > Add Interpreter > Add Local Interpreter — select the interpreter type and browse to:

_build\windows-x86_64\release\kit\python\python.exe

The build generates all SDK source roots in .idea/lightspeed-kit.iml (from the committed template), so no manual interpreter-path configuration is needed — all imports (carb, pxr, omni.*, py7zr, pygit2, requests, etc.) resolve out of the box.

5. Reload sources after a build#

The build regenerates .idea/lightspeed-kit.iml from the template with updated source roots. PyCharm monitors this file and hot-reloads it — a restart is not required. To pick up the changes:

  • Alt-Tab away from PyCharm and back — PyCharm refreshes its virtual file system on window focus, which is usually enough.

  • If that doesn’t work: click the Reload All from Disk toolbar button (or File > Reload All from Disk) to force PyCharm to re-read the .iml and update the project model.

Rebuild (.\build.bat) whenever you add new pip dependencies, update extension dependencies, or add/remove extensions so that _build/ and the .iml source roots stay in sync.

Run Configurations#

The .run/ folder contains pre-configured run profiles organized into folders. They appear in PyCharm’s run dropdown automatically:

Run#

Configuration

Type

What it does

Edition

Run Remix (Release)

Shell

Launches lightspeed.app.trex.bat (full app)

Any

Run Remix (Dev)

Shell

Launches lightspeed.app.trex_dev.bat (dev app)

Any

Debug#

Configuration

Type

What it does

Edition

Debug Remix (Release)

Compound

Starts debug server + launches full app with debugger

Professional

Debug Remix (Dev)

Compound

Starts debug server + launches dev app with debugger

Professional

Attach to Debugger

Remote Debug

Attaches to PyCharm’s debug server on 127.0.0.1:33100

Professional

Debugging#

  1. Select Debug Remix (Dev) or Debug Remix (Release) from the run dropdown.

  2. Click the Debug button (bug icon).

  3. Set breakpoints and debug normally — the app connects to PyCharm automatically.

These are compound configurations that start PyCharm’s debug server (port 33100) and launch the app with omni.flux.debug.pycharm in one step.

For general debugging concepts, test debugging, and the debugpy-based alternative, see Debugging Guide.

Formatting & Linting#

Run format_code.bat and lint_code.bat all from the terminal, or wire them as PyCharm external tools for hotkey integration:

Settings (Ctrl+Alt+S) > Tools > External Tools > + (Add):

Field

Format Code

Lint Code

Name

Format Code

Lint Code

Program

$ProjectFileDir$\format_code.bat

$ProjectFileDir$\lint_code.bat

Arguments

(leave empty)

all

Working directory

$ProjectFileDir$

$ProjectFileDir$

Then assign keyboard shortcuts: Settings (Ctrl+Alt+S) > Keymap > External Tools — right-click the tool and assign a shortcut.

Project Structure#

Excluded directories#

The following directories are excluded from indexing (defined in .idea/lightspeed-kit.iml.template):

_build, _compiler, _repo, _testoutput, rtx-remix

If you need to exclude additional directories: Settings (Ctrl+Alt+S) > Project > Project Structure — select the folder and click Excluded.

Tip: Do not use an _* wildcard pattern to exclude — it will also exclude __init__.py files and break Python resolution.

Search scopes#

Two shared scopes are pre-configured via .idea/scopes/ and available immediately:

  • Source Extensions — file:source/extensions//* — all files in project extensions

  • Python Extensions — file:source/extensions//*&&file:*.py — only Python files in extensions

Use them in Find in Files (Ctrl+Shift+F) by selecting the scope dropdown. To add custom scopes: Settings (Ctrl+Alt+S) > Appearance & Behavior > Scopes.

What’s Committed#

Summary of all shared configuration files in the repository:

.idea/ (project settings)#

File

Purpose

lightspeed-kit.iml.template

Template for generated .iml (source roots, etc.)

modules.xml

Module mapping

misc.xml

Python SDK type, Ruff enabled

vcs.xml

Git VCS mapping

encodings.xml

UTF-8 default encoding

fileTypes.xml

.kit → TOML file type association

externalDependencies.xml

Required plugins (TOML, Shell Script)

fileTemplates/internal/Python Script.py

SPDX Apache-2.0 license header for new Python files

fileTemplates/internal/Python Unit Test.py

AsyncTestCase scaffold with license header

scopes/Source_Extensions.xml

Search scope: all extension files

scopes/Python_Extensions.xml

Search scope: Python extension files only

inspectionProfiles/profiles_settings.xml

Inspection profile settings

.gitignore

Excludes user-specific files (workspace, tasks, etc.)

.run/ (run configurations)#

File

Folder

Purpose

Run Remix (Release).run.xml

Run

Launch full app

Run Remix (Dev).run.xml

Run

Launch dev app

Debug Remix (Release).run.xml

Debug

Debug full app (Professional)

Debug Remix (Dev).run.xml

Debug

Debug dev app (Professional)

Attach to Debugger.run.xml

Debug

Remote debug server connection (Professional)

Tips#

Widescreen tool window layout#

Enable Settings (Ctrl+Alt+S) > Appearance & Behavior > Appearance > Widescreen tool window layout to prevent the bottom tool window (terminal, run output, etc.) from spanning the full window width. With this option on, the left and right side panels (Project, Structure, etc.) extend to full height and the bottom pane only fills the space between them. This is especially useful on ultrawide or wide monitors where horizontal space is abundant.