customizing maya

david | | Sunday, March 2nd, 2008

One of the things that makes maya so powerful is the way it can be customised at so many different levels. The user interface allows you to add tool shelves and marking menus and to designate hot-keys to launch just about any function. The mel scripting language (and more recently python) can be used to create functionality that goes beyond the out-of-the-box set of tools. And an API allows plugins to be written and compiled.

I reckon most people can benefit from customising maya even if all they do is download a few mel scripts from highend3d. This article may be of interest to people just starting out on the path to customised nirvana, and shows how I have configured my environment and where I put stuff. It is written by a maya2008 windows XP user - that's me - and its not the only way to do it, but these things work for me.

A default installation puts maya in C:\Program Files\Autodesk\Maya2008. I prefer to reserve the C:\Program Files folder for operating system programs. I make a second partition and logical drive called D: for all non-operating system programs. It stops me messing up my C:drive. So maya goes to D:\Program Files\Autodesk\Maya2008

When you start maya for the first time the default location of the "maya application directory" folder is C:\Documents and Settings\david\My Documents\maya. (Who ever made up the name "Documents and Settings" is probably still laughing. It was a joke - right? Had to be.) The maya application directory is where all your maya preferences get stored and is the default location for your projects folder. Rather than clutter the C: drive with my maya prefs and projects I use a second hard drive, which in my case is on a file server (optional). The file path is K:\david\maya.

I use a windows environment variable called MAYA_APP_DIR to tell maya where to look. This can be set up by right-clicking on "My Computer" and choosing properties to bring up the System Properties window. Then in the advanced tab click "Environment Variables" and then click "New" in the "user variables" section.

Maya trys to be flexible when it comes to folder locations. There are several places it will look by default when searching for things like mel scripts and icons. I dont like to leave things to chance so I use the Maya.env file to specifically define file paths for different things. Maya.env just contains a user specified list of environment variables that are only used by maya.

(note: MAYA_APP_DIR needs to be set in the system properties. All others can be set in Maya.env).

You may have one or more copies of Maya.env which is by default an empty text file. I found them in K:\david\maya and K:\david\maya\2008. I deleted the first one and used the one in K:\david\maya\2008. If you dont have one, just create a text file called Maya.env.

I will explain the actual contents of my Maya.env in the next few sections.

Mel scripts are a great way to customize maya. You can write your own or download from a huge selection available online. If you are not careful you can end up in a bit of a mess. You can even upset the core functions of maya. A little organisation goes a long way and will make future trouble-shooting much easier.

Dont believe everything you read! Most, but not all, mel scripts you download will come with some form of installation instruction. It is common to write instructions as comments in the top of the mel file. Sometimes there is a seperate text file. Either way you need to understand a bit about how maya uses mel scripts so that you can decide whether to follow the suggested installation or your own methods instead.

My most important rule is to NEVER put any custom mel script into the maya installation folder.

I use K:\david\maya\2008\scripts as the location for all custom mel scripts. Then I create sub-folders to keep my custom script collection organized. So, for example, K:\david\maya\2008\scripts\comet contains almost 30 scripts written by Michale Comet. K:\david\maya\2008\scripts\djx are the scripts I wrote myself. K:\david\maya\2008\scripts\zoo contains over 170 scripts that make up Hamish McKenzie's zooToolbox. And so on.

K:\david\maya\2008\scripts is one of the places maya will look, by default, for custom scripts, but it will not look into the sub-folders. This is where I use Maya.env to point to the various script locations. I add the following line to Maya.env

MAYA_SCRIPT_PATH = K:\david\maya\2008\scripts;K:\david\maya\2008\scripts\comet;K:\david\maya\2008\scripts\zoo;K:\david\maya\2008\scripts\djx;K:\david\maya\2008\scripts\AE;K:\david\maya\2008\scripts\mods

This configures the MAYA_SCRIPT_PATH environment variable and gives it a list of the script folders. (note: this needs to be a single line in Maya.env, not split over two lines like it appears above)

In fact maya will look for scripts in the local folders specified by the MAYA_SCRIPT_PATH variable before it searches the installation scripts folder. Scripts found in the local scripts folder take precedence over the ones in the installation folders. This is important to know. If you put a script in your local scripts folder with the same name as the one in the installation folder, then the local version over-rides the installation version. This could make maya behave in unexpected ways - or you could use it as a way to tweek and change the way maya works by editing a local copy of a maya script. Then it is easy to revert to the original script if something goes wrong. If maya starts to act strangely you can temporarily rename your local scripts folder, to hide them, and see if the problem is a custom script.

I use K:\david\maya\2008\scripts\mods as the location for scripts from the maya installation that I have modified in some way. In this folder I also keep a text file where I keep a list of the changes I made to each script. When I update the maya installation, I need to check whether my modified scripts are still current, or whether the original scripts were changed in the update. In this case I then need to transfer my modifications to the updated versions of the scripts, and my notes help me remember what I changed in the first place.

Often mel scripts create user interfaces that use bitmaps for the buttons and icons. These days, the default location that maya searches for them is K:\david\maya\2008\prefs\icons (although some people still write their mel scripts with special paths hard-coded in the script). When I started using maya it was also common to put bitmaps in a folder called K:\david\maya\bitmaps and I have continued to use that folder. Once again I use Maya.env to tell maya where to look. I add the following line.

XBMLANGPATH = K:\david\maya\bitmaps;K:\david\maya\bitmaps\js;

The example shows two paths; the main bitmaps folder and a sub-folder, called js, where I put the icons for Jan Sandstrom's many mentalray shaders.

Custom plugins can be a bit of a trap. If you start to rely on them and you update to a new version of maya then you need to also get an update for the plugin. Plugins (unlike mel scripts) must be recompiled for each version of maya. For this reason I am fairly cautious about incorporating plugins into my general work-flow. When I do use them, I put the .mll files in K:\david\maya\2008\plugins
and add the following line to Maya.env

MAYA_PLUG_IN_PATH = K:\david\maya\2008\plugins;

Commercially available plugins usually come with their own installation routine. I still like to make sure I know where the files will end up, and if given a choice I will direct then to somewhere in D:\Program Files\

Mentalray shaders can have upto 4 different components; a shader called xxx could have these 4 files - xxx.mi, xxx.dll, render_xxx.xpm, AExxxTemplate.mel. Each file needs to be put in the correct location and maya needs to know where it is. Like with mel scripts, I dont like to put custom shaders into the maya installation folders.

I put the xxx.mi in K:\mentalray\include, xxx.dll in K:\mentalray\lib, render_xxx.xpm in my K:\david\maya\bitmaps folder and AExxxTemplate.mel in a sub-folder of my scripts folder called K:\david\maya\2008\scripts\AE (have a look back at my MAYA_SCRIPT_PATH and you will see it listed there).

I define a new environment variable called MI_CUSTOM_SHADER_PATH by adding the following line to Maya.env

MI_CUSTOM_SHADER_PATH = K:\mentalray\lib;K:\mentalray\include;

(note; In versions of maya prior to 8.5 you had to also edit a file called maya.rayrc to declare the shader, but this nolonger required.)

When maya starts up it checks your scripts folder and if it finds this mel script it will execute it. This gives you the ability to run mel commands and launch other mel scripts to set up the user interface when you start maya.

My userSetup.mel launches several mel scripts to add menus to maya's main window menu. For example it contains the line

source cometMenu.mel;

which adds a menu that gives me access to a whole bunch of Michael Comet's mel scripts.
Another example is a little work-around for a maya bug where every so often it forgets to load the Mayatomr plugin (aka the mentalray renderer). The following line checks for it and loads it if its not found.

if(!`pluginInfo -query -l -n Mayatomr`) loadPlugin "Mayatomr";

What I have written here should be viewed as an example of how one person chose to configure their environment. There are many ways you could do this, and many factors could affect your choices. My main concerns are keeping things organized and keeping things seperate from the default maya installation.


  1. RE: Customizing Maya
    I made a mess of it David.

    Comment by jeremy — March 15, 2008 @ 10:32 pm

  2. Very useful information. Thanks a lot for explaining this stuff so clearly.

    Comment by Skip Jennings — June 14, 2008 @ 7:53 am

  3. hi!
    David Johnson
    First of all thank you for your selfless dedication, I customizing maya, it is a mel:

    if (! `pluginInfo-query-l-n Mayatomr`) loadPlugin "Mayatomr";
    When I put it in when loaded into userSetup.mel, maya error:
    / / Error: if (! `PluginInfo-query-l-n Mayatomr`) loadPlugin "Mayatomr";
    / /
    / / Error: "C: / Documents and Settings / li / My Documents/maya/7.0/scripts/userSetup.mel" line 1.52: Syntax error / /

    How to solve this problem, thank you

    Comment by carli — July 3, 2008 @ 1:40 pm

  4. Oh! I understand that, I made a minor mistake, I put "mayatomr" symbol wrong.

    Problem has been resolved!

    Comment by carli — July 3, 2008 @ 1:51 pm

  5. Hi David hi guys,
    i have a problem under Windows 7. I copied the old folder i had in my OS Vista and paste in the new installed Windows 7 and i having problems to load in my Shelf images and get run Scripts that i had in me personalized script folder.

    Are you running in the same trouble? Do you know how to solve this problem?

    @ David,
    i sent you and eMail. Did you get it?

    Thank you in advance.
    Best Regards,

    Comment by 2xbo — February 18, 2010 @ 8:02 pm

  6. [...] more about setting up Maya for customization on djx’s blog. [...]

    Pingback by Maya.env Configuration of Variables Using userSetup.mel and | CG Hijinks — March 23, 2011 @ 7:26 am

  7. Hi David,

    I have always loved this post and this has been my setup for a long time.

    I have a question about how you could take this one step further.

    I have our studio setup up like above where all our artists have a user environment MAYA_APP_DIR variable pointing to a shared file on our server. This means artist can go to any machine, log in, and have the same custom shelves, scripts, shaders etc on any machine.

    One of the issues we have though is that artists have their own little habbits and want their own custom shortcuts/layouts etc. When they change a hotkey for example it gets changed for all users. Or if they change a tool setting it gets set to those values for all.

    How could I go the next step and introduce local user prefs, but still maintain our studio default scripts/shelves and shaders for each user. Basically I want to make it so our studio defaults replace the maya install defaults (without actually moving all our folders into the install directory of maya on each machine) and then have users able to have their own maya prefs on top of the studio ones.

    Any advice would be great.



    Comment by chuckie7413 — August 26, 2011 @ 3:59 am

  8. Hi Rich. Its a good question, and the answer maybe deserves its own page. Maybe something along the lines of "Customizing Maya in a Shared Environment". However here's a quick answer...

    My preferred way of sharing a common setup across the studio is to store the scripts, plugins, bitmaps, etc in a shared network location, which I'll refer to as the "central server". But I do not point MAYA_APP_DIR to that location and this avoids the problem you mentioned where one user's preference changes affect all users. Each user sets MAYA_APP_DIR to a folder on their local machine. For neatness this can be set up the same way on all machines, but does not have to be. Then, and this is the important bit, each user gets a copy of the admin approved Maya.env file, which they must place in their local scripts folder. This Maya.env can be very simple and include a single environment variable, MAYA_SCRIPT_PATH which points to a folder in the central server that contains the (admin approved) userSetup.mel.

    So everybody has their own local MAYA_APP_DIR but courtesy of their approved copy of Maya.env they are all starting with the same centralized userSetup.mel.

    userSetup.mel is used to enforce the same config on all of the local machines and it does this by setting environment variables and sourcing or running mel and python scripts. It can also be used to copy plugins form the central server to the local machine (making it easier to update plugin files while people are still working - they get the update next time they start maya). And it can be used to overwrite user prefs on the local machine so that each new maya session starts with the same prefs.

    Actually I dont like forcing people to all use the same prefs, so I dont do that last bit. In fact I think users should have some control of their own environment so I add a line at the end of the central userSetup.mel to source a local file called "localUserSetup.mel" (ie this could be their old personal userSetup.mel just renamed). Users are free to add what ever config stuff they like to their localUserSetup.mel

    I think this system gives a good balance between central control and user customization. New scripts, plugins, menus and shelves etc can be set up by the admin and will be available to all users when they restart maya, but users will still be able to create or change hotkeys and other prefs and add their own mel scripts to the mix. To set up a new user, all I have to do is give them the official copy of Maya.env.

    Ok... that was a bit longer than I thought it would be.

    Comment by david — August 27, 2011 @ 6:47 pm

  9. Hey David,

    Thanks so much for getting back to me. I did not have RSS feeds for comments on this post so only just seen your reply.

    That sounds like a great way of doing it!

    I am not too familiar with the UserSetup.mel file. I normally use it to force maya to source scripts it sometimes fails to read. I will read up on it (believe there are lots of blog posts about it)

    I contacted Autodesk support (as we have subscription support) and do you know what they said when I asked for some advice on a possible setup:

    "I will check around but as far as I can tell there is no way of setting up a configuration that you are requesting"

    That is what I get for paid support!!

    The community is lucky there are people like you who are willing to share their knowledge and experiences with others.

    Much appreciated and I will let you know our re-setup goes :-)



    Comment by chuckie7413 — August 31, 2011 @ 5:16 am

  10. You can do just about anything with userSetup.mel. Something to be aware of though is the order and way in which maya loads stuff at startup. This can cause some headaches.

    For example, userSetup may load a plugin and then try to do something with it, like set up a default configuration. Maya loads plugins as a kind of background process, so a mel command attempting to do something with the plugin may fail because the plugin is not loaded yet.

    Another case is where you may have modified mel scripts in your central scripts path, and you want these to override the originals that are part of the maya install. Depending on the script, maya may have already sourced the original script before it gets to userSetup, so if you are using userSetup (as I suggested) to set up scripts and plugins paths, you may have to also source the modified scripts so that maya knows it should use yours instead of the originals which it already saw.

    I could give more examples, but I might leave it at that for now. Generally, once you get the hang of how maya loads, you can figure out a strategy to get your setup working.


    Comment by david — September 1, 2011 @ 11:58 pm

  11. Hi David,

    Just wanted to update as to what we did with the new setup.

    Users no longer have a MAYA_APP_DIR environment variable set but instead have their own user maya preferences folders. (I have made each users Windows Profile a roaming one, so the maya folder created in their user My Documents folder is called no matter what machine they are on)

    Each user then gets a copy of our custom studio Maya.env file that loads up all our custom scripts, shelves and shaders upon startup of maya.

    This now works really well meaning users can maintain their own style and layout while having access to the studios shared scripts and shaders.

    I have avoided playing with the userSetup.mel file for now as everthing seems to be running nicely as is.

    Many thanks for your help.

    I should also thank my friend Anthony Tan ( for his IT supoprt.



    Comment by chuckie7413 — September 16, 2011 @ 12:17 am

  12. I came across an issue with if(!`pluginInfo -query -l -n Mayatomr`) loadPlugin "Mayatomr"; in my
    It appeared not to load everything necessary to get mentalCore to load, so to get around the issue I changed it to say

    import maya.utils as mu

    and it still loaded mentalRay but then mentalCore loaded completely aswell.
    Maybe there is something not loading completely when using that method...Just fyi.

    Comment by markserena — February 28, 2012 @ 1:03 pm

  13. Yes I think sometimes plugins have dependencies on other things and require a deferred load to work properly. (It is also how plugins are loaded when specified for autoload in the plugin manager.)

    Thanks for showing us the python. In mel that would be something like this

    if(!`pluginInfo -query -l -n Mayatomr`) evalDeferred("loadPlugin \"Mayatomr.mll\"");

    Usually a direct load works for me, but good to know a solution when it doesn't.

    Comment by david — March 1, 2012 @ 11:46 pm

RSS feed for comments on this post.

Leave a comment

You must be logged in to post a comment.

Powered by WordPress | Based on a theme by Roy Tanck