Maya.env Configuration of Variables Using “userSetup.mel”

maya2011_thumbuserSetup.mel Tutorial Part 1: Theory and Practical Use

Difficulty: Novice

Do you not want your tools to be on your work computer?  Do you need multiple users to use your tools without a lot of setup?  This is the simplest and most reliable solution.  You can keep your Maya installation directory clean and organized by storing your scripts, icons, shelves, plug-ins, tutorial example files, and the like in one accessible location on your hard drive or an external hard drive.  Most of mine are on my thumb drive I bring with me everywhere and a backup lives on a portable hard drive.  If you’re like me, you can’t live without your tools!

UPDATE: If you wanna know more advanced techniques, read Part 2.

In this directory are multiple folders that belong to a particular project, tutorial, or set of tools.  I like to know that when I back up my mel tools from my C:\ drive that I can just drag and drop one “Library” folder to the external or thumb drive and be done with it instead of rooting through the maya

This is all good, but what happens when I try to run or source scripts and load shelves automatically from within Maya that are dependent on these files?  By default, Maya doesn’t “see” these files when running things automatically.  Therefore, you have to tell Maya before it gets started that the files are located in those locations or you’ll get errors.  Broadening Maya’s “vision” involves doing things like editing Maya.env files to suit your needs.

Alternately, the userSetup.mel file is a powerful and underused tool to tell Maya where to source all the things I just described before the program starts.  It’s very easy to edit as long as you are familiar with mel.  I think the biggest payoff is that while I am working on several different machines, I only need to copy this one file to Maya’s “C:\Users\Jonas\Documents\maya\2011-x64\scripts” directory.  If I know that the userSetup.mel will be sourcing mel scripts that will work in all currently installed versions of Maya and the machine does indeed have multiple versions installed, I just copy it once into “C:\Users\Jonas\Documents\maya\scripts” and that should do it for all versions of Maya.  I know then that Maya is going to find all the scripts, icons, plug-ins, and other things it needs to run my tools without annoying errors.

The real work happens when trying to figure out a system for storing all your tools into consistently named file structures and keeping all that organized.  When you download or create new tools that need to be installed using this userSetup method all you really need to do is organize it, rename some files to match your directory specs, and update the userSetup with the new directories that Maya needs to “see”.


I recently wanted to install some tools for use with a DVD about rigging.  Instead of dragging and copying all those files to the default Maya ones and cluttering up those directories, I simply dragged them all a  directory I predesignated for ALL my tools called “Library”.  In the Library there are sub-folders each for a specific project or tool.  In each project directory there are specifically named folders like icons, shelves, scripts, example_files, and plugins.

If you’ve downloaded installations for mel scripts, shelves, or plugins you’ll notice that they also have the same directory structure unless it’s a messy release.  If it is messy, it now is your job to make it organized and rename those directories to something at least YOU can understand.  So getting back to the installation, I kept the files in one project directory with its organized directory substructure and just placed them in my Library of tools.  Next is the juicy mel bit.  If you are a beginner mel scripter then refer to the code below and try and decipher what it’s doing.

//Puts a directory into the MAYA_SCRIPT_PATH and prints the result.
global proc putMayaScriptPath (string $path) {
    if (!`filetest -d $path`) error ($path + " does not exist.");
    string $newScriptPath = $path + ";" +`getenv "MAYA_SCRIPT_PATH"`;
    putenv "MAYA_SCRIPT_PATH" $newScriptPath;

//Prints MAYA_SCRIPT_PATH as list
global proc printMayaScriptPaths () {
    string $list = `getenv "MAYA_SCRIPT_PATH"`;
    print "\n\nPrinting MAYA_SCRIPT_PATH Paths...\n----------\n";
    string $buffer[];
    int $numTokens = `tokenize $list ";" $buffer`;

    if ($numTokens >= 1){

        for ($b in $buffer){

            print ($b + "\n");


//Puts a directory into the Maya XBMLANGPATH and prints the result.
global proc putXbmlangpath (string $path) {
    if (!`filetest -d $path`) error ($path + " does not exist.");
    string $xpmLangPath = $path + ";" + `getenv "XBMLANGPATH"`;
    putenv "XBMLANGPATH" $xpmLangPath;

//Prints XBMLANGPATH as list
//Use to query where Maya is looking for .xpm files
//Note: it uses X-B-M even though the filetype Maya uses is X-P-M
global proc printMayaXpmPaths () {
    string $list = `getenv "XBMLANGPATH"`;
    print "\n\nPrinting XBMLANGPATH Paths...\n----------\n";
    string $buffer[];
    int $numTokens = `tokenize $list ";" $buffer`;

    if ($numTokens >= 1){

        for ($b in $buffer){

            print ($b + "\n");



//Puts a directory into the Maya BMPLANGPATH and prints the result.
global proc putBmplangpath (string $path) {
    if (!`filetest -d $path`) error ($path + " does not exist.");
    string $bmpLangPath;

    if (`getenv "BMPLANGPATH"` == "") {
        $bmpLangPath = $path;
    } else {
        $bmpLangPath = $path + ";" + `getenv "BMPLANGPATH"`;

    putenv "BMPLANGPATH" $bmpLangPath;

//Prints BMPLANGPATH as list
//Use to query where Maya is looking for .bmp files
global proc printMayaBmpPaths () {
    string $list = `getenv "BMPLANGPATH"`;
    print "\n\nPrinting BMPLANGPATH Paths...\n----------\n";
    string $buffer[];
    int $numTokens = `tokenize $list ";" $buffer`;

    if ($numTokens >= 1){

        for ($b in $buffer){

            print ($b + "\n");



/******************************************************************************* -------------------------------------------------------------------------------- AFR Tools -------------------------------------------------------------------------------- *******************************************************************************/ string $afrScripts = "C:/Users/Jonas/Documents/maya/Library/AFR/scripts"; string $afrIcons = "C:/Users/Jonas/Documents/maya/Library/AFR/icons"; //Put AFR script path to MAYA_SCRIPT_PATH. putMayaScriptPath $afrScripts; //Put AFR xmp path to Maya XMPLANGPATH. putXbmlangpath $afrIcons; //Put AFR bmp path to Maya BMPLANGPATH. putBmplangpath $afrIcons; //Put AFR bmp path to Maya MAYA_SHELF_PATH. putMayaShelfPath $afrShelf;
//Print the result in the script editor after Maya starts up to assess any problems. printMayaScriptPaths; printMayaXpmPaths; printMayaBmpPaths; printMayaPlugInPaths; print "\n----------\n";

You can even create a shelf that pops up automatically when you start up. It’s better to *create* shelves in the userSetup.mel rather than sourcing shelf files. Problems typically occur if you try to edit the shelf env using `putenv Maya_Shelf_Path` from within the userSetup.mel so I just make a window that is comprised of all my shelves. If you want to source shelves at startup, you can set a Windows environment variable called Maya_Shelf_Path and point it to “C:/Users/User/Documents/maya/Library/shelf/myshelves”, or wherever you’d like.

This (below) will create a shelf with a button that saves the shelf if you middle mouse drag new buttons to it. Neato! FIRST, remember for the button to work you must create an empty .mel file in that location ( look in the code where it says “C:/myCustomShelves/\” ) before pressing the button! Change it to whatever you want, drag/create new buttons, save, copy the shelf file contents to your userSetup if you want to auto-create the shelf in your custom shelves window when Maya starts up. Point the save path to the default maya shelves location to have the shelf pop up in your Maya shelves.

global proc jaMyShelf () {
    if ( `window -exists myWindow` )
      deleteUI -window myWindow;
      windowPref -remove myWindow;

    window -title "My_Shelves" myWindow;


        string $ja_sh1 = `shelfLayout -style "iconOnly" -backgroundColor .5 .5 .5 "myShelf"`;

                -enableCommandRepeat 1
                -enable 1
                -width 34
                -height 34
                -manage 1
                -visible 1
                -preventOverride 0
                -align "center"
                -label "Save This Shelf"
                -labelOffset 0
                -font "tinyBoldLabelFont"
                -image "commandButton.xpm"
                -image1 "commandButton.xpm"
                -style "iconOnly"
                -marginWidth 1
                -marginHeight 1
                -command ("global proc saveThisShelf(){\r\n"
                    +"\tstring $ja_sh1 = `shelfLayout -q -p \"myShelf\"`;\r\n"
                    +"\tstring $shelf = `tabLayout -q -selectTab $ja_sh1`;\r\n"
                    +"\tstring $tempDir = \"C:/myCustomShelves/\";\r\n"
                    +"\tstring $name = (\"shelf_\" + $shelf);\r\n"
                    +"\tsaveShelf( $shelf, ($tempDir + $name) );\r\n"
                    +"\tprint ( $shelf + \" was saved\");\r\n"
        setParent ..;



It can be as easy or complex as you want.  This is a pretty simple example of what you can do.  I may do some more examples of more complex things in the future, so stay posted.

You will notice I threw in my own print command called printMayaScriptPaths into the code or something similar to print one of these Maya environment script paths.  I use those to print a legible list that isn’t one big long horizontal  string, but a vertical list with new lines in the script editor when Maya starts.  I didn’t include all the print commands in this block, but a couple of small edits to the printMayaScriptPaths and that’ll do it if you are familiar with reading and editing mel.  Putting this in your userSetup.mel will successfully add new folders to Maya’s environment for scripts, xpm, and bmp icons.

After installing the userSetup into its proper home, see above, and putting the files into my Library, all there is to do is run Maya and see what happens.  If I try to load a shelf tool do the icons appear?  Are my plugins loaded and my scripts able to be sourced?  For this example, loading the shelf tool associated with these icon paths and script path is indeed successful.  It seems like a lot of work, and it really can be if you’re a professional or a hard core enthusiast.  After trying to explain it, it takes a lot to just to break down this simple theory.  In reality it takes time to keep things organized and in working order when you’re bouncing from one machine to the next and you have a ton of tools and scripts like I do,  but if you have a system like this nailed down it’s simple to keep it all ship shape.

A couple of reasons why I do it this way is because I like to have everything I want Maya to do before startup to be in one location, this userSetup, and that way I can track down any problems quickly by just looking at the script editor.  When Maya loads, I can see all my tools and paths are being sourced successfully along with where they all live from the script editor as well.  If something breaks, everything is in one place without a lot of unnecessary  folders and clutter.  When I move my tools or back them up it’s all as simple as drag and drop one folder and a mel script.

Some will say, well why not use a Maya.env file, and well, it is the same thing but just another file to have to keep track of.  *Edit: I ate my own words today so look for a post going over maya.env and userSetup for Mac OSX coming soon.  OSX FAILS AND THIS TECHNIQUE WILL NOT WORK*  After much hair-pulling, I decided to retreat from OSX and never use Maya on that OS if I can ever help it.  It is severely limited.

If you are becoming or are a seasoned veteran then odds are you are using the userSetup to create some command ports or something along with using a Maya.env file so why not combine the two processes and save yourself some time in the long run?  The userSetup can live in a spot that’s more accessible as well.  It is also a good skill to have, knowing what is happening at each stage of startup–before, during, and after.  Finally, you are on your way to making your Maya tools travel with you with far less time setting up on a new computer.  Just carry your tools and your userSetup with you and you’re good to go!

There are other environment variables can you set with this method as well.  Some things you may want to do require a little more “umph” than a userSetup.mel file can do… more about userSetup and setting environment variables in a future post.

  • rajesh

    respected sir
    iam rajesh i want to purchase desktop
    which configration is sutibale for maya and other application
    plz give configration
    thanking u sir

    • Jonas Avrin

      Depends on how you will be using Maya. For me, using it on an Intel based Macbook Pro works very well. I rig and model mostly. I do not suggest using Maya in OSX.

  • Pingback: Maya.env Configuration of Variables Using userSetup.mel and | CG Hijinks()

  • Pingback: Studio Level Managment Of Scripts and Tools in Maya |

  • jerk001

    exactly what i was looking for, thnx Jonas,,

    • Jonas Avrin

      Yup, there’s another post on this too. You might have noticed. They are dated techniques but still they get the job done.