Skip to content

Set up PyCharm for Python Houdini 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 PyCharm via environment variables, 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.

Increase IDE limits for large stub files (prevents completion from breaking on big .pyi files): - PyCharm → Help → Edit Custom Properties… - Add the following lines, then save:

idea.max.intellisense.filesize=200000
idea.max.content.load.filesize=200000

Restart PyCharm if it’s currently open.

Enable the JetBrains Toolbox script for PyCharm: - 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

Start the project window with the regular PyCharm command and keep it running:

pycharm <project_root>

If the script directory isn’t on your PATH, use the full path:

"$HOME/Library/Application Support/JetBrains/Toolbox/scripts/pycharm" <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

Point Houdini to PyCharm via environment variables in houdini.env: - File location: $HOME/Library/Preferences/houdini/<version>/houdini.env (for example, 21.0). - Add the following lines:

HOUDINI_EXTERNAL_EDITOR="$HOME/Library/Application Support/JetBrains/Toolbox/scripts/pycharm"
EDITOR="$HOME/Library/Application Support/JetBrains/Toolbox/scripts/pycharm"
VISUAL="$HOME/Library/Application Support/JetBrains/Toolbox/scripts/pycharm"

Restart Houdini. Then use “Edit in External Editor” in a Python node. The file should open in the already‑running PyCharm project window (the one you started with pycharm <project_root>).

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 you have a PyCharm project window started via pycharm <project_root> and keep it running before invoking the external editor from Houdini.
  • Completion/indexing broken with large stubs: confirm you set the custom properties (idea.max.intellisense.filesize, idea.max.content.load.filesize) and restart PyCharm.
  • Houdini opens a different window: first start the target project via pycharm <project_root> and keep it running; then use “Edit in External Editor.”