Houdini 18.5 Nodes TOP nodes

Python Script TOP node

Creates work items that run a script

On this page
Since 17.5

This node creates work items that run a Python script (in-process or as a scheduled job) during the work item generation phase. You can configure this behavior with the Evaluate Script During menu.

If the script is configured to run during the generation step, then the code is evaluated immediately after the work item is created. No additional work is done while the work item is cooking. You can use this mode to create attributes programmatically instead of using the Attribute Create node.

If you select one of the other evaluation modes, then the work item evaluates the script code when it cooks. In-process scripts can access a larger amount of information about the PDG graph as well as other objects and settings within the current Houdini session. If you run the script out-of-process, then the script is limited to accessing the attributes of the work item it is associated with and anything the script can import.

The node will always create exactly one work item per upstream item, with the contents of the Python Code field as the work to be done for that item. To generate a custom work item configuration, you should use the Python Processor node instead.


The $HH/help/files/pdg_examples/top_pythonscript example shows how you can use this node to interact with both in-process and out-of-process work items.



Generate When

Determines when this node will generate work items. You should generally leave this set to "Automatic" unless you know the node requires a specific generation mode, or that the work items need to be generated dynamically.

All Upstream Items are Generated

This node will generate work items once all of the input nodes have generated their work items.

All Upstream Items are Cooked

This node will generate work items once all of the input nodes have cooked their work items.

Each Upstream Item is Cooked

This node will generate work items each time a work item in an input node is cooked.


The generation mode is selected based on the generation mode of the input nodes. If any of the input nodes are generating work items when their inputs cook, this node will be set to Each Upstream Item is Cooked. Otherwise, it will be set to All Upstream Items are Generated.

Evaluate Script During

Determines when the script code stored on this node is evaluated.

Cook (Out-of-Process)

A scheduler runs the script out-of-process during the cook stage.

Cook (In-Process)

Runs the script during the cook stage in the same process as the Houdini session.


Runs the script when the work item is generating.

Copy Inputs to Outputs

When on, the Python Script node automatically copies input files to its output file list. This is useful when you are not planning to add any new output files to your script and you want to pass the same inputs to the downstream node.

Expand Variables in String Attributes

When Evaluate Script During is set to Cook (Out-of-Process), this toggles determines whether or not PDG should expand $variables in string attributes when loading the work item into the standalone Python process. Variable expansion includes any environment variable, as well as PDG-specific tokens like PDG_DIR or PDG_TEMP.

Python Executable

The following parameters configure which Python executable to use to run the script code and what arguments to pass to the executable.

These parameters are only available when the node is configured to run out-of-process by the Cook (Out-of-Process) option in the Evaluate Script During menu.

Python Bin

Determines which Python executable to use to run the script.


Use hython to run the script.

PDG Python

Use PDG Python to run the script.


Use a custom Python executable to run the script.

Custom Python Bin

Determines the path to the Python executable.

This parameter is only available when Python Bin is set to Custom.

Python Arguments

Specifies the extra arguments to pass to the Python executable itself to configure the behavior of the interpreter.

Script Arguments

Specifies the arguments to pass to the Python script. These values are accessible in the script through sys.argv[1:].

Reset Python Path Variables

When on, resets the PYTHONHOME and PYTHONPATH variables that are defined by Houdini in the external Python process. This is necessary when using a Python version that is incompatible with the one that is built into Houdini.

Python Code

The Python code that is run for each work item.

When running out-of-process, the Python interpreter specified by Python Bin or Custom Python Bin saves the code to disk and executes it. The script has access to the work_item variable which provides an API to access the name, index, frame, and attributes of the work item associated with the script. Additionally, you can use the intData, floatData, and strData helper functions to query attributes on the work item.

When running in-process or during the generation stage, the Python interpreter embedded in Houdini runs the code. In addition to the work_item variable, the self and parent_item variables are also available. The self variable is a reference to the node that owns the work item and the parent_item variable is a reference to the parent or None.


TOP Scheduler Override

This parameter overrides the TOP scheduler for this node.

Work Item Priority

This parameter determines how the current scheduler prioritizes the work items in this node.

Inherit From Upstream Item

The work items inherit their priority from their parent items. If a work item has no parent, its priority is set to 0.

Custom Expression

The work item priority is set to the value of Priority Expression.

Node Defines Priority

The work item priority is set based on the node’s own internal priority calculations.

This option is only available on the Python Processor TOP, ROP Fetch TOP, and ROP Output TOP nodes. These nodes define their own prioritization schemes that are implemented in their node logic.

Priority Expression

This parameter specifies an expression for work item priority. The expression is evaluated for each work item in the node.

This parameter is only available when Work Item Priority is set to Custom Expression.


CreateAttributes Example for Python Script TOP node

This example file demonstrates creates work item attributes using a Python Script node.

PythonScript Example for Python Script TOP node

This example demonstrates how the Python Script node can be used to run Python code in process or out of process.

See also

TOP nodes