Houdini 20.0 Reference

Starting Houdini from the command line

On this page

Command line options

If you start Houdini from the command line, you can specify options, and also optionally a list of files to open (.hip scene files, .cmd or .py scripts, .hda libraries to load).

houdini [options] [file ...]

Houdini recognizes the following options.


In macOS and Linux, when you run Houdini from the command line, by default it “backgrounds” itself, returning control of the terminal to the shell. This option instead keeps Houdini in the “foreground”, meaning you won’t be able to type more commands to the shell until Houdini exists or you press ⌃ Ctrl + Z to pause the foreground process.


Houdini will “background” itself after starting, returning control of the terminal to the shell. This is the default.


Define the window geometry on the screen (see also -span). For example

houdini -geometry=WxH+X+Y

(where W is width, H is height, X is horizontal position, and Y is vertical position). The geometry specification cannot have spaces. X and Y may be negative (in which case you would use - instead of + as a separator). Some window managers do not allow larger windows than the screen, overlapping of manager toolbars, and/or positioning offscreen.


When this option is specified, Houdini will output Performance Monitor events to the terminal or window console for tasks performed during Houdini startup. The -profile-startup option can also accept a a file path argument. For example:

houdini -profile-startup=/path/to/startup.hperf

In this case Houdini will save Performance Monitor statistics to the specified file rather than output Performance Monitor events to the terminal or window console. The saved file can be loaded into Houdini’s Performance Monitor pane for inspection. Note that the file name should end with an .hperf extension for the Performance Monitor pane to see the file by default.


When you specify this option on a computer with multiple monitors, Houdini will start up spanning all monitors, so the main Houdini window fills them all (where possible, discounting resolution differences and non-rectangular layouts). This only works on some window managers, and has no effect in single-monitor setups. Cannot be used with -geometry.

-screen N

Which screen to open the main Houdini window on (for computers with multiple monitors). Note the space between the option and the screen number.

-s name / -desktop name

The pane layout to start up with. These are listed in the Desktop menu in Houdini, such as Build or Technical. You can list all available layouts in a Python shell using hou.ui.desktops.

See pane layouts for more information about switching and saving desktop layouts.


This starts up Houdini using the named desktop, but does not change the default desktop preference.


The maximum number of threads Houdini may use. Note no space between option and the number of threads.


Start Houdini in “manual” cook mode.


Start Houdini in Apprentice mode. This will use an Apprentice or FX License.


Start Houdini in Core mode. This will require a Core license, unless -force-fx-license is also used.


Start Houdini in Indie mode. This will require an Indie license, unless -force-fx-license is also used.


Force Houdini to use an FX license, even if it would not normally use one. Combine with -core to run Houdini Core using an FX license.


If mixed in with the files to load, specifies a point at which Houdini should wait until the GUI is available before loading the rest of the files.

For example:

houdini -foreground myscript.cmd waitforui setupshelf.py my.hip

In this example, Houdini would load myscript.cmd immediately, but wait until the GUI was available before loading setupshelf.py and my.hip. This is useful for scripts that require certain UI elements to function (such as desktops, shelves, or panes).


Automatically start Houdini Engine SessionSync. You must specify the type of connection (pipe or port) and a pipe name or port number.

For example, to use a named pipe :

houdini -hess=pipe:name

(where name is the name of the pipe).

To use a socket:

houdini -hess=port:number

(where number is a port number between 1024 and 65535).

Exit codes

If started from the command line, Houdini may exit with one of the following codes:


No error.


Generic error (catch-all code).


Misuse of shell built-ins (according to Bash documentation)


Failure to check out or verify an appropriate product license.


Socket communication failure.


Error while parsing UI definition file (.ui).


User interface

  • Menus

    Explains each of the items in the main menus.

  • Viewers

    Viewer pane types.

  • Panes

    Documents the options in various panes.

  • Windows

    Documents the options in various user interface windows.


  • Expression functions

    Expression functions let you compute the value of parameters.

  • Expression cookbook

    Tips and tricks for writing expressions to accomplish various effects.

  • Python scripting

    How to script Houdini using Python and the Houdini Object Model.

  • VEX

    VEX is a high-performance expression language used in many places in Houdini, such as writing shaders.

  • HScript commands

    HScript is Houdini’s legacy scripting language.

  • hwebserver

    Functions and classes for running a web server inside a graphical or non-graphical Houdini session.

Command line

Guru level

Plugin installation

  • Houdini packages

    How to write and combine multiple environment variable definition files for different plug-ins, tools, and add-ons.

Houdini Engine