Maya Paths & Customization

I’ve spent a lot of time figuring out how to customize Maya; it really has an excellent system allowing you to change almost anything. The underlying system for allowing this is based on several Path variables that Maya will check to see where it should load its functionality from. With clever use of these it’s possible to create a predictable, modular system for allowing customization from different projects, or for individual users. I’ve documented how Maya handles each of the important Path variables, and have a couple of suggestions for how to set them up.

Diagnosing Path Issues

From within Maya you can use the mel commands ‘getenv’ and ‘putenv’ to get and store environment variables. Changing the variables like this is volatile, it’s only for this instance of Maya. You can use the ‘whatIs’ command to query where a specific script or command is being run from.

I’ve also written a little script to give a nice UI for checking the environment variables – envBrowser

Variables

MAYA_APP_DIR  – default is `%USERPROFILE%/My Documents/maya` MAYA_LOCATION – Defaults to the directorys that Maya is being run from (eg, `%PROGRAMFILES%/Autodesk/maya<version>`) This can be changed, but must point to a directory containing a valid Maya install, if not Maya will revert back to defaults.

Script Paths – MAYA_SCRIPT_PATH

When trying to find a script or command Maya will search through the script path from top to bottom until it finds it, then stop. This means that scripts higher up the path will override lower ones, including any of Mayas own default scripts. So to edit an installed script you can copy it to your local My Documents script folder and it will then ignore the original.

  • Current Project
    • The default if you haven’t set your own is: %MAYA_APP_DIR%/projects/default. Annoyingly if you set a mel directory in the project settings then it doesn’t add it to the scripts path, and Maya won’t find your scripts.
  • User environment variables System environment variables
    • It will only look at the first one of these, then skip the rest.
  • Maya.env %MAYA_APP_DIR%/<version >/Maya.env %MAYA_APP_DIR%/Maya.env
    • It will only look at the first one of these, then skip the rest. Can only define one MAYA_SCRIPT_PATH and it will use the first it comes to within the file, any others will be ignored. If you want to add multiple directories then add them all to one line, using semi-colons to seperate them.
  • %MAYA_APP_DIR%/<version>/scripts
  • %MAYA_APP_DIR%/scripts
  • %MAYA_APP_DIR%/<version>/presets
  • Shelf paths
    • All locations from %MAYA_SHELF_PATH% are added here
  • %MAYA_APP_DIR%/<version>/prefs/shelves
  • %MAYA_APP_DIR%/<version>/prefs/markingMenus
  • %MAYA_LOCATION%/scripts/startup
  • %MAYA_LOCATION%/scripts/others
  • %MAYA_LOCATION%/scripts/AETemplates
  • %MAYA_LOCATION%/scripts/paintEffects
  • %MAYA_LOCATION%/scripts/fluidEffects
  • %MAYA_LOCATION%/scripts/hair
  • %MAYA_LOCATION%/scripts/cloth
  • %MAYA_LOCATION%/scripts/fur
  • Modules

userSetup.mel Maya will only run this script once, and will use the first one it comes to in the path system. To allow us to define a team userSetup but still allow a user to run their own scripts, we use a userSetup file that is provided by the team project. After completing team setup, this file will try to run ‘localSetup.mel’ which the user can customize.

Module Paths – MAYA_MODULE_PATH

Maya searches ‘MAYA_MODULE_PATH’ for module definition files; a text file that contains the name of the module and the location it is installed. For each module path found, it appends the suffixes “plug-ins”, “presets”, “scripts”, and “icons”, and adds them to MAYA_PLUG_IN_PATH, MAYA_PRESET_PATH, MAYA_SCRIPT_PATH (and PYTHONPATH), and XBMLANGPATH, respectively.

  • User environment variables System environment variables
    • It will only look at the first one of these, then skip the rest.
  • %MAYA_APP_DIR%/<version>/modules
  • %MAYA_APP_DIR%/modules
  • Maya’s doing something weird for this next set of paths, it seems it might be defined in the registry, and a newer version of maya will continue to use an older directory if it still exists. So this could be in different places on different machines.
    • %PROGRAMFILES%/Common Files/Alias Shared/Modules/maya/<version>
    • %PROGRAMFILES%/Common Files/Alias Shared/Modules/maya OR
    • %PROGRAMFILES%/Common Files/Autodesk Shared/Modules/maya/<version>
    • %PROGRAMFILES%/Common Files/Autodesk Shared/Modules/maya
  • %MAYA_LOCATION%/modules

Plug in Path – MAYA_PLUG_IN_PATH

Any directories listed here will be added to the Plugin Manager window in Maya, however, in the same manner as scripts, Maya will use the first plugin it finds in the list, and then ignore any further plugins named the same. Even when selecting to autoload a specific plugin, when restarting Maya the ‘autoload’ checkbox will move to the first plugin it finds. The only exception to this is when you load the plugin manually by clicking the ‘Loaded’ checkbox, it will correctly load the specified plugin. Also you can load a specific plugin in a script by stating the full path of the plugin to load.

  • User environment variables System environment variables
    • It will only look at the first one of these, then skip the rest.
  • %MAYA_APP_DIR%/<version>/plug-ins
  • %MAYA_APP_DIR%/plug-ins
  • %MAYA_LOCATION%/plug-ins
  • Modules

Shelf Path – MAYA_SHELF_PATH

If you query this variable it doesn’t report Mayas default shelf directory, I think it only checks here: %MAYA_APP_DIR%/<version>/prefs/shelves

  • User environment variables System environment variables Maya.env
    • It will only look at the first one of these, then skip the rest.
  • Mayas own stuff

Icons – XBMLANGPATH

Maya searches the ‘XBMLANGPATH’ variable for icons, the variables ‘MAYA_ICON_PATH’ and ‘MAYA_FILE_ICON_PATH` are obsolete and are no longer used.

  • User environment variables System environment variables
    • It will only look at the first one of these, then skip the rest.
  • %MAYA_APP_DIR%/<version>/prefs/icons
  • %MAYA_APP_DIR%/prefs/icons
  • %MAYA_LOCATION%/icons
  • %MAYA_LOCATION%/app-defaults
  • %MAYA_LOCATION%/icons/paintEffects
  • %MAYA_LOCATION%/icons/fluidEffects
  • %MAYA_LOCATION%/icons/hair
  • %MAYA_LOCATION%/icons/cloth
  • %MAYA_LOCATION%/icons/live
  • %MAYA_LOCATION%/icons/fur
  • Modules

Python scripts – PYTHONPATH

Similar to mel scripts, Maya will search through the path until it finds what it’s looking for, then will stop. This allows you to override scripts by placing them higher up the path. Note that ‘Modules’ is above the My Docs scripts which is different than for all the other paths. Mayas default locations aren’t shown in the PYTHONPATH variable, to see the full path that python is using, query the sys.path variable in Python.

  • %MAYA_LOCATION%/bin
  • User environment variables System environment variables
    • It will only look at the first one of these, then skip the rest.
  • Modules
  • %MAYA_LOCATION%/bin/python25.zip
  • %MAYA_LOCATION%/Python/DLLs
  • %MAYA_LOCATION%/Python/lib
  • %MAYA_LOCATION%/Python/lib/plat-win
  • %MAYA_LOCATION%/Python/lib/lib-tk
  • %MAYA_LOCATION%//bin
  • %MAYA_LOCATION%/Python
  • %MAYA_LOCATION%/Python/lib/site-packages
  • %MAYA_APP_DIR%/<version>/prefs/scripts
  • %MAYA_APP_DIR%/<version>/scripts
  • %MAYA_APP_DIR%/scripts

userSetup.py This is handled slightly differently than the mel equivalent, Maya will execute all userSetup.py files it finds in the PYTHONPATH directories, they will be ran in the order found. Also, this file is ran before Mayas UI is created, so cannot be used to access or hack any of the default Maya UI. Any print commands will be output to the ‘Output Window’ instead of the Script Editor History.