Houdini 20.5 Python scripting

Command-Line Scripting

On this page

Accessing hou from a Regular Python Shell

You can integrate Houdini into your Python scripts by importing the hou module in a regular Python shell. The first time you import hou, Python will load all of Houdini’s libraries and initialize an empty Houdini session. The hou module effectively stores a Houdini session, and you can load into that session from a hip file, inspect that file from your script, and input and output information to and from nodes in that session.

To import the hou module, you first need to instruct Python to search $HFS/houdini/pythonX.Ylibs for Python modules. This can be accomplished either by appending the path to the PYTHONPATH environment variable before starting Python, or by appending the path to sys.path in Python.

Tip

The $HHP environment variable is a convenience variable that point to $HFS/houdini/pythonX.Ylibs. It is set when sourcing the houdini_setup script.

The following Python snippet imports the hou module into a standard Python shell. The snippet assumes that the houdini_setup script was sourced beforehand.

def enableHouModule():
    '''Set up the environment so that "import hou" works.'''
    import sys, os

    # Importing hou will load Houdini's libraries and initialize Houdini.
    # This will cause Houdini to load any HDK extensions written in C++.
    # These extensions need to link against Houdini's libraries,
    # so the symbols from Houdini's libraries must be visible to other
    # libraries that Houdini loads.  To make the symbols visible, we add the
    # RTLD_GLOBAL dlopen flag.
    if hasattr(sys, "setdlopenflags"):
        old_dlopen_flags = sys.getdlopenflags()
        sys.setdlopenflags(old_dlopen_flags | os.RTLD_GLOBAL)

    # For Windows only.
    # Add %HFS%/bin to the DLL search path so that Python can locate
    # the hou module's Houdini library dependencies.  Note that 
    # os.add_dll_directory() does not exist in older Python versions.
    # Python 3.7 users are expected to add %HFS%/bin to the PATH environment
    # variable instead prior to launching Python.
    if sys.platform == "win32" and hasattr(os, "add_dll_directory"):
        os.add_dll_directory("{}/bin".format(os.environ["HFS"]))

    try:
        import hou
    except ImportError:
        # If the hou module could not be imported, then add 
        # $HFS/houdini/pythonX.Ylibs to sys.path so Python can locate the
        # hou module.
        sys.path.append(os.environ['HHP'])
        import hou
    finally:
        # Reset dlopen flags back to their original value.
        if hasattr(sys, "setdlopenflags"):
            sys.setdlopenflags(old_dlopen_flags)

enableHouModule()
import hou

Note

If you do not run source houdini_setup, you must set the HFS and/or HHP environment variables manually.

Note

On Windows, you must add %HFS%/bin to the DLL search path by calling os.add_dll_directory() prior to importing the hou module. This enables Python to locate the hou module’s Houdini library dependencies.

In Python 3.7, os.add_dll_directory() does not exist. Add %HFS%/bin to the PATH environment variable before Python is launched instead.

Note

When you import the hou module, the Houdini initialization scripts 123.cmd/123.py and 456.cmd/456.py will run.

Note

On Linux, you may encounter a warning about JE Malloc not being configured. JE Malloc helps improve memory performance in Houdini’s operations.

To configure JE Malloc, preload the jemalloc library when starting Python. For example:

LD_PRELOAD="$HFS/dsolib/libjemalloc.so" python

You can alternatively disable the JE Malloc warning by setting HOUDINI_DISABLE_JEMALLOCTEST=1 in the environment before importing the hou module.

Note

On macOS, you may encounter “symbol not found” errors when importing the hou module. In that case, you can pre-emptively load the Houdini libraries before the hou module is imported by setting the DYLD_INSERT_LIBRARIES variable in the environment before launching Python. For example:

export DYLD_INSERT_LIBRARIES=/Applications/Houdini/HoudiniX.Y.ZZZ/Current/Version/Houdini

Licensing

When you import the hou module, Python will check out a license. By default, it will use a Houdini Batch license, and use a Houdini FX license if no batch license could be found. If you want it to use a Houdini license, you can set the HOUDINI_SCRIPT_LICENSE variable to hescape before importing the hou module. You can also set this variable from within your Python script with os.environ['HOUDINI_SCRIPT_LICENSE'] = 'hescape'.

By default, the hou module will not return the Houdini license until the Python interpreter exits. However, if you have a long running Python script and want to quickly acquire and release a license, you can call hou.releaseLicense() when you are done with the hou module. Subsequent calls into the hou module will reacquire the license. Note that Houdini’s session data and libraries will not be unloaded from memory until Python exits.

The hou module, when imported by Python or Houdini, will loop through the directories in $HOUDINI_PATH, and for each directory found, append that directory plus /scripts/python to sys.path. For example, you can put your Python modules in the directory $HOUDINI_USER_PREF_DIR/scripts/python and they will be in the Python search path after you import hou.

hython

Hython is a Python shell that ships with Houdini that is slightly different from the standard Python shell in the following ways:

  • It automatically adds $HHP to sys.path and imports the hou module when it starts up.

  • You can pass .hip files on the command line and it will load them.

  • It supports tab completion, and you can press tab twice to list possible completions (on Linux and Mac).

  • You can run hscript commands from an interactive shell by prefixing them with %.

  • It can receive and handle Houdini openport commands while waiting for console input when you start it with the -b option.

By default, hython does not listen in the background for and run commands sent to openport sockets, but you can enable this behavior with the -b option. When listening for openport events, hython uses a different mechanism to read command-line input than the standard Python one. Note that this other mechanism may leave the console in a bad state if hython forks into the background or exits prematurely, and it can behave strangely when editing lines that wrap.

Python scripting

Getting started

Next steps

Reference

  • hou

    Module containing all the sub-modules, classes, and functions to access Houdini.

Guru level

Python viewer states

Python viewer handles

Plugin types