Skip to content

Configuring PyCharm for Houdini Python on macOS

Setting up PyCharm to understand Houdini’s hou on macOS can be confusing. This guide walks you through creating a project‑local virtual environment from Houdini’s embedded Python, installing type stubs, adding Houdini’s runtime paths to the interpreter, wiring Houdini’s External Editor to a dedicated PyCharm launcher, and verifying everything so you get precise completion and navigation — without touching Houdini’s bundled interpreter.

Note

Platform: macOS. Tools: SideFX Houdini, JetBrains PyCharm, JetBrains Toolbox.

Important

Objective: precise Code Insight for Houdini’s hou in PyCharm using a project‑local .venv/ created from Houdini’s Python. Houdini’s bundled interpreter remains untouched; all packages land in .venv/.

Houdini setup

Collect Houdini’s Python search paths for IDE analysis. In a Python node, run:

import sys
import pathlib
import json

sys_paths = [pathlib.Path(p).resolve().as_posix() for p in sys.path]
print(json.dumps(sys_paths, indent=4))

Copy the JSON array for later.

Tip

You only need these paths once. They let PyCharm resolve the same modules Houdini injects at runtime.

PyCharm setup

Create a virtual environment from Houdini’s Python (standard macOS “Current” path):

/Applications/Houdini/Current/Frameworks/Python.framework/Versions/Current/bin/python3 -m venv .venv

Activate it when working in a shell:

source .venv/bin/activate

Select the project interpreter in PyCharm: - Preferences (Cmd + ,) → Project: → Python Interpreter → gear → Add… → Existing environment → choose .venv/bin/python → OK.

Install type stubs into .venv:

pip install -U pip types-houdini types-PySide2

Note

types-houdini adds .pyi stubs for hou. types-PySide2 provides Qt stubs often used with Houdini.

Add Houdini’s runtime paths to Interpreter Paths (so the IDE sees the same modules): - Preferences → Project: Python Interpreter → gear → Show All… → select your .venv interpreter → folder icon (Interpreter Paths). - Add only the entries from your JSON that are missing when running .venv/bin/python outside Houdini → Apply.

Enable the JetBrains Toolbox script for PyCharm and create a clearly named wrapper: - Toolbox App → Settings → enable “Generate shell scripts.” - In Toolbox, open PyCharm’s entry → enable its shell script (on macOS it is typically at): - ~/Library/Application Support/JetBrains/Toolbox/scripts/pycharm - Create a dedicated launcher for Houdini:

mkdir -p "$HOME/bin"
ln -s "$HOME/Library/Application Support/JetBrains/Toolbox/scripts/pycharm" \
      "$HOME/bin/pycharm-houdini"

Start the project window with this launcher and keep it running:

"$HOME/bin/pycharm-houdini" <project_root>

Important

Keeping this project window open ensures that files opened from Houdini land in this exact PyCharm window, which is configured to use .venv/.

Back to Houdini

Wire Houdini to PyCharm now that the pycharm-houdini launcher exists: - Edit → Preferences → Set External Text Editor → set to: - ~/bin/pycharm-houdini

Use “Edit in External Editor” in a Python node. The file should open in the already‑running PyCharm project window (the one launched with pycharm-houdini).

Silence unresolved hou warnings in project files (type‑check only):

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    import hou  # IDE/type-check only; ignored at runtime inside Houdini

Verify

In an editor tab:

node = hou.pwd()
geo = node.geometry()

If geo appears as Any, declare the context explicitly (SOP example):

node: hou.SopNode = hou.pwd()
geo = node.geometry()

You should now have precise completion and navigation.

Troubleshooting

  • import hou fails when running outside Houdini: expected. The IDE uses stubs for analysis; the real hou exists only inside Houdini.
  • Modules unresolved in PyCharm: ensure Interpreter Paths were added to the same .venv interpreter selected for the project; confirm the project is running from pycharm-houdini before invoking the external editor from Houdini.
  • Houdini opens a different window: first start the target project via pycharm-houdini and keep it running; then use “Edit in External Editor.”