Dealing with houdini.env

I continually run into confusion from Houdini users about how the Houdini.env is supposed to work, what the syntax is supposed to be, or even what it does in the first place. It’s easy if you’ve been trapped in pipeline land (like me) to think that environment configuration is even a little bit intuitive, when really the syntax can be pretty arcane. So here’s a quick breakdown of the whys and hows of environment configuration.

What’s an environment?

Environment variables are used widely outside Houdini… think of the “PATH” variable on most operating systems as an example. PATH is used as a way to define default locations for the shell to find executables. For example, on most systems, python.exe is added to PATH during installation. This allows a user or program to launch Python simply by executing python in the shell instead of having to type /usr/bin/env/python or C:/Python27/python.exe or whatever. If you want to see what’s in your PATH variable, you can open a shell (Command Prompt on Windows, Terminal on UNIX-based systems) and type the following command:

Windows: echo %PATH%

Unix: echo $PATH

There are tons of environment variables at the system level; PATH is just one of the most common ones. You can see all of them by typing set in Windows, or printenv in Unix. Environment variables are extremely handy for helping different applications work together by agreeing on common “terms” like “what’s this project’s root path?” and “what version of Houdini am I allowed to use on this project?” and as such they are routinely used/abused by pipeline devs to help organize projects and teams.

If you want a variable to have multiple values, all you have to do is separate the values by ; on Windows, or : on Unix.

Environment variables vs. shell variables

Many of the environment variables you see when using the above commands are “environment variables”, meaning they are always there system-wide. You can also have “shell variables”, which affect the current “shell” or command line environment. These variables exist for the current shell and all child processes of that shell, but they don’t affect any other processes running on the system. You can set shell variables using the following commands:

Windows: set VARNAME=value

Unix: export VARNAME=value

These shell variables are the key to Houdini.env (and Maya.env, and others). Houdini automatically looks for a Houdini.env file in a specific location, and if it finds it, it will add or modify any existing variables with the definitions contained within. These variables are then used by Houdini to apply specific configurations or preferences (like displaying the splash screen or deciding with GPU to use), or to know where to look for assets or plug-ins. There’s a full list of the variables Houdini understands here. You can also add any old variables you like here; for example, you could add in FARTZ="$HOME/cat_gifs" and then refer to that path inside Houdini using $FARTZ, or in other parts of the Houdini.env file the same way, or use that variable in your Python scripts in Houdini via os.environ.get('FARTZ'), etc.

Houdini-specific gotchas

Houdini has a bit of special sauce in its environment syntax that isn’t obvious at first. The most common special characters you’ll see are @ and &. These little guys are very important, so don’t overlook them! @ is a shortcut that means “whatever’s in my HOUDINI_PATH”. So if your HOUDINI_PATH is $HIP;$HFS/houdini;$HOME/houdini, and you were to write HOUDINI_PATH=@/otls, this would set your HOUDINI_PATH to $HIP/otls;$HFS/houdini/otls;$HOME/houdini/otls. & expands to “the default for whatever this variable I’m setting is”. This is the big one that can trip people up. If Houdini doesn’t know what the default path is to scan for OTLs, scripts, toolbars, and the like, it simply won’t include them at all, and you’ll end up with all kinds of errors and missing pieces when Houdini starts up. For this reason, it’s essential that your HOUDINI_PATH includes & in its definition, so that Houdini knows to look in the usual places to find OTLs and scripts and all those nice things that make it actually work.

What really trips people up here is when they’re trying to install a few different plugins or tools simultaneously, and they’re not sure how or what to set HOUDINI_PATH to. Some people end up setting HOUDINI_PATH multiple times during the environment; others try to set everything at once at the end. The key is to actually pay attention to what your paths are actually expanding to when you set them, and to remember that you are SETTING the variable each time you define it, not APPENDING to it.

This will make more sense with a quick example:

# add MOPS to environment
MOPS="C:/Users/Henry/Documents/MOPS"
HOUDINI_PATH=$HOUDINI_PATH;$MOPS

# add gamedev toolset to environment
HOUDINI_PATH=$HOUDINI_PATH;$APPDATA/SideFX/GameDevToolset/17.5/1.196;&
PATH=$APPDATA/SideFX/GameDevToolset/17.5/1.196/bin;$PATH

Notice how each of those variables, HOUDINI_PATH and PATH, are redefined by including the original variable somewhere in there. This ensures that any new values are appended to the existing value, rather than replacing them.

Another very important thing to remember here is that sneaky little & at the end of the HOUDINI_PATH definition. A lot of people get in the habit of adding it to every single HOUDINI_PATH definition in their environment file. The problem with this is that now your HOUDINI_PATH is going to be filled up with repeated entries for all the paths that & expands to. Houdini scans for all the paths in HOUDINI_PATH in the order in which they’re defined, and if you have any scripts or OTLs or anything that are supposed to supersede the defaults, having the default paths mixed in in the middle of all your definitions multiple times can lead to unexpected results.

The safest way to handle this is to always include the & at the very end of the final definition of your HOUDINI_PATH, and nowhere else. This means that if you’re defining HOUDINI_PATH multiple times in your environment like the examples above, only the very last definition should have that & in there.

TL;DR

The rules are simple:

• If you’re defining a variable VAR more than once, include $VAR somewhere in that definition. Example: PATH=$PATH;/new/path
• Only include & at the end of the last definition of HOUDINI_PATH.

This whole process was made much easier using “packages” as of Houdini 17.5, but until third-party developers start widely adopting the package system as part of their installation process, you’ll likely have to keep fiddling with your Houdini.env as you upgrade and install new stuff. And beware: some of those programs will not follow the above rules when modifying your environment, so it’s best to double check your Houdini.env after upgrading Redshift or whatever!