Installation

Supported Platforms

Our goal is to support the 3 latest versions of Maya. At the time of this writing, that means 2008, 2009, and 2010.

Versions of Maya and Python

Maya Version Python Version Supported
8.5 2.4.3 No
2008 (including: sp1, ext1, sp2, ext2) 2.5.1 Yes
2009 (including: sp1, sp1a) 2.5.1 Yes
2010 2.6.1 Yes

PyMEL Package

Easy Install

As of version 0.9.1 PyMEL supports installation via setuptools, which makes it a lot easier to get started if you’re not well-versed in the intricacies of the PYTHONPATH. If you don’t already have setuptools installed it will be downloaded for you when you run the install command below, but in order for this to all go smoothly you must have the following things:

  • a connection to the internet
  • write permission to your Maya installation directory

If you fall short on either of these you can always perform a Manual Install of PyMEL.

Installation on OSX

  1. Open a shell: you’ll find the Terminal app in /Applications/Utilities

  2. cd to the directory where you extracted the pymel zip file. A file called “setup.py” should exist directly below this directory. For example, I downloaded and extracted mine to my “Downloads” folder:

    cd ~/Downloads/pymel-1.0.0

    Note

    On OSX and Linux you have to escape spaces in folder names ( or you can press the Tab key to auto-complete paths ). Here is an example of escaping a space in a folder name (notice the backslash after Image):

    cd /Applications/Image\ Capture.app
  3. Next, from the shell, run the installation for each version of Maya that you have installed:

    sudo /Applications/Autodesk/maya2008/Maya.app/Contents/bin/mayapy setup.py install
    sudo /Applications/Autodesk/maya2009/Maya.app/Contents/bin/mayapy setup.py install
    sudo /Applications/Autodesk/maya2010/Maya.app/Contents/bin/mayapy setup.py install

    You should be able to drag and drop the mayapy executable from the finder into the shell to get the path.

Installation on Windows

  1. Open a shell: from the Start menu go to “Run...”, then type in cmd and press “OK”

    Note

    On Windows Vista and above you will need to open cmd as administrator. To do this right-click the Command Prompt and select Run as administrator.

  2. cd to the directory where you extracted the pymel zip file. A file called “setup.py” should exist directly below this directory. For example, I downloaded and extracted mine to my desktop:

    cd "C:\Desktop\pymel-1.0.0"
  3. Next, from the shell, run the installation for each version of Maya that you have installed:

    "C:\Program Files\Autodesk\Maya2008\bin\mayapy.exe" setup.py install
    "C:\Program Files\Autodesk\Maya2009\bin\mayapy.exe" setup.py install
    "C:\Program Files\Autodesk\Maya2010\bin\mayapy.exe" setup.py install

    You should be able to drag and drop the mayapy.exe executable from windows explorer into the shell to get the path. Don’t forget to wrap it in quotes.

    Note

    Be sure to use the proper path to your mayapy.exe. For example, if you have 32-bit maya installed on 64-bit windows, it will be installed to C:\Program Files (x86) instead of C:\Program Files

Manual Install

If the easy install did not turn out to be so easy, PyMEL can always be manually installed like any other python module or package. The process is simple in concept:

  1. put the extracted pymel folder somewhere
  2. tell python where to find it

To find available modules, python searches directories set in an environment variable called PYTHONPATH. This environment variable can be set for each Maya installation using the Maya.env file, or it can be set at the system level, which will set it for all instances of python, including those bundled with each Maya installation (aka “mayapy”).

Maya.env System-Level
allows per-maya configuration of environment variables YES NO
allows easy execution of maya and mayapy in a shell NO YES

Note

If you set your PYTHONPATH at the system level it will override any values for PYTHONPATH set in Maya.env, except on OSX when launching Maya from it’s application bundle (an application bundle is the icon you click on to launch Maya).

Manual Method 1: Setting Up Your Environment Using Maya.env

The instructions below on setting up your python environment are essential to learning how to properly deploy any python module, not just PyMEL, and mastering them is also key to using the Standalone Maya Python Interpreter.

Warning

installation instructions have changed since version 0.9, so pay attention. PyMEL now includes a partial override of the maya package. This means that both the pymel and maya sub-directories must be on the python path, and they must come before the standard maya package in the search path. To keep things simple, we are now recommending that the top-level pymel-1.0.x directory be added to the PYTHONPATH instead of copying the pymel sub-directory.

  1. extract the pymel zip file that you downloaded. The directory structure should look something like this:

    pymel-1.0.0
    |-- docs
    |-- examples
    |-- extras
    |-- maya*
    |   `-- app
    |       `-- startup
    |-- pymel*
    |   |-- api
    |   |-- cache
    |   |-- core
    |   |-- internal
    |   |-- tools
    |   |   |-- bin
    |   |   |-- mel2py
    |   |   `-- scriptEditor
    |   `-- util
    |       `-- external
    |           `-- ply
    `-- tests
The folders marked with an asterisk are the required pymel packages, which must be on the PYTHONPATH. If you wish to relocate PyMEL, be sure to move both the pymel and maya folders.
  1. Locate the Maya.env for the desired version of Maya and open it in your favorite text editor. Maya.env can be found in your MAYA_APP_DIR under a sub-directory for each version of Maya.
OS MAYA_APP_DIR
Linux ~/maya
OSX ~/Library/Preferences/Autodesk/maya
Windows drive:\My Documents\maya
  1. Once open, add a line to set PYTHONPATH to the top-level directory where you extracted pymel (the directory that contains both pymel and maya folders). The PYTHONPATH variable is a list of paths separated by semi-colons (on windows) or colons (on osx and linux). For example:

On Windows:

PYTHONPATH = C:\path\to\pymel-1.0.0;C:\path\to\something_else

On OSX and Linux:

PYTHONPATH = /path/to/pymel-1.0.0:/path/to/something_else

Manual Method 2: Setting Up Your System Environment

OSX and Linux

Setting up your python paths at the system level on OSX and Linux is a little bit involved. I will focus on OSX here, because Linux users tend to be more technical.

When you open a terminal on OSX ( /Applications/Utilites/Terminal.app ), your shell may be using one of several different scripting languages. (You can easily tell which is being used by looking at the label on the top bar of the terminal window, or the name of the tab, if you have more than one open. ) It will most likely say “bash”, which is the default, so that is what I will explain here.

To set up python at the system level using bash, first create a new file called .profile in your home directory ( usually something like /Users/yourname and denoted in a shell with the shortcut ~/ ). Inside this file paste the following, being sure to set the desired Maya version:

export MAYA_LOCATION=/Applications/Autodesk/maya2009/Maya.app/Contents
export PATH=$MAYA_LOCATION/bin:$PATH
export PYTHONPATH=/path/to/pymel-1.0.0

Here’s a line-by-line breakdown of what you just did:

  1. set MAYA_LOCATION, a special Maya environment variable that helps Maya determine which version to use when working via the command line ( be sure to point it to the correct Maya version).

  2. the PATH environment variable is a list of paths that will be searched for executables. Each path is separated by a colon :.By adding $MAYA_LOCATION/bin you can access all the executables in the Maya bin directory from a shell without using the full path. For example, you can launch Maya by typing maya, or open a Maya python interpreter by typing mayapy.

    If you manually installed pymel and ipymel, include the path to the directory where the ipymel script resides. For example, if the path to the ipymel script is /path/to/pymel-1.0.0/pymel/tools/bin/ipymel, the line might look like the following:

    export PATH=$MAYA_LOCATION/bin:/path/to/pymel-1.0.0/pymel/tools/bin:$PATH
  3. finally, set the PYTHONPATH to ensure that python will see the pymel and maya packages. Like the PATH environment variable, PYTHONPATH is a list of paths separated by colons :.

Windows XP
  1. Open the Start Menu, right-click on “My Computer” and then click on “Properties”. This will open the “System Properties” window.

  2. Changed to the “Advanced” tab, then click on the “Environment Variables” button at the bottom.

  3. In the new window that pops up, search through your “User Varaibles” on top and your “System Variables” on the bottom, looking to see if the PYTHONPATH variable is set anywhere.

    If it is not set, make a new variable for either your user or the system (if you have permission). Use PYTHONPATH for the name and for the the value use the directory above the pymel directory. So, for example, if the pymel directory is C:\My Documents\pymel-1.0.0\pymel copy and paste in the value C:\My Documents\pymel-1.0.0 from an explorer window.

    If PYTHONPATH is already set, select it and click “Edit”. This value is a list of paths separated by semi-colons. Scroll to the end of the value and add a semi-colon ; and after this add the directory above the pymel directory to the end of the existing path. For example, let’s say the starting value is:

    C:\Python25\lib

    If the top-level pymel directory is C:\My Documents\pymel-1.0.0\pymel, the edited value would be:

    C:\Python25\lib;C:\My Documents\pymel-1.0.0
  4. Add and set your MAYA_LOCATION. For example, for 2008 it would be:

    C:\Program Files\Autodesk\Maya2008
  5. Next, find and edit your PATH variable. Append the following to the end of the existing value:

    %MAYA_LOCATION%\bin

    Don’t forget to put a semi-colon ; between the existing paths and the new ones that you are adding.

    If installing ipymel include the path to your ipymel bin directory. For example, if you manually installed PyMEL, the line should look like the following:

    %MAYA_LOCATION%\bin;C:\My Documents\pymel-1.0.0\pymel\tools\bin

Manual Method 3: sitecustomize

If you have don’t write permission to your Maya installation directory and you can’t change your PYTHONPATH then you’ve come to the right place. This method relies on a special module in python called sitecustomize to dynamically insert PyMEL into the path when python starts.

An advantage of this approach is that it allows for an arbitrary block of code to execute, which means you can use whatever logic you like to determine in what cases to add PyMEL, what version to use, etc.

A potential disadvantage of this approach is that it adds PyMEL to the python path system-wide, instead of just inside Maya. However, there are a number of utilities in pymel.util that are useful outside of Maya as well, so this could be an advantage as well.

Here’s how to setup PyMEL using sitecustomize:

  1. open your favorite text editor

  2. paste in the text below:

    import sys
    sys.path.insert(0,'/path/to/top-pymel-dir')
    
  3. Replace the /path/to/top-pymel-dir line with the path to the folder where you extracted PyMEL. The folder you want should contain both ‘pymel’ and ‘maya’ folders directly below it

  4. save this file as sitecustomize.py somewhere in your system python path. If you are unsure what your python path is, you can run this from the python tab in the script editor to find out.

    import sys
    for i in sys.path: print i
    

Note

If your studio is already using sitecustomize.py and you can’t edit it, you can use the same instructions with the filename usercustomize.py instead. usercustomize is loaded immediately after sitecustomize and is intended for this situation.

ipymel

ipymel is an extension of the ultra-customizable IPython interpreter, which enables it to easily work with mayapy and PyMEL. It adds tab completion of maya depend nodes, dag nodes, and attributes, as well as automatic import of PyMEL at startup. Many more features to come.

ipymel Easy Install

As of version 0.9.2 ipymel is automatically installed when “easy” installing PyMEL, but you may have to do a few extra steps to get it working properly on Windows.

Windows Only:
  • Install python on your system. Install only the exact versions of python that come with Maya ( see Versions of Maya and Python )
  • Install pyreadline for windows from the IPython website. By default it will install to your system copy of Python.
  • Copy the pyreadline directory, and all the pyreadline.* files from your system site-packages directory ( ex. C:\Python25\Lib\site-packages ) to your Maya site-packages directory ( ex. C:\Program Files\Autodesk\Maya2008\Python\lib\site-packages ).

To Run: In a new shell, run the following command:

ipymel

Note

The “easy” installation method produces an invalid ipymel.exe on 64-bit windows systems. As of this writing I’m still looking into this.

Note

Though not a requirement for ipymel to work, it’s best to read up on Manual Method 2: Setting Up Your System Environment

ipymel Manual Install

OSX and Linux

  1. Follow the installation instructions above for Manual Method 2: Setting Up Your System Environment

  2. Install IPython. For a manual install, I recommend downloading the tarball, not the egg file. Unzip the tar.gz and put the sub-directory named IPython somewhere on your PYTHONPATH, or just put it directly into your python site-packages directory

  3. Open a terminal and run:

    chmod 777 `which ipymel`
  4. then run:

    ipymel
    

Windows

  1. Follow the installation instructions above for Manual Method 2: Setting Up Your System Environment

  2. Install python for windows, if you have not already.

  3. Install IPython using their windows installer. The installer will most likely not find the maya python install, so install IPython to your system Python instead (from step 1).

  4. Install pyreadline for windows, also from the IPython website

  5. Copy the IPython directory, pyreadline directory, and all the pyreadline.* files from your system site-packages directory ( ex. C:\Python25\Lib\site-packages ) to your Maya site-packages directory ( ex. C:\Program Files\Autodesk\Maya2008\Python\lib\site-packages ).

  6. open a command prompt ( go to Start menu, then click ‘Run...’, then enter cmd ). Once it is open execute the following line to start ipymel:

    ipymel.bat
    

Troubleshooting

Linux

If you encounter an error installing on linux, you may have to fix a few symlinks. Here’s how you check. cd to the directory where you unzipped pymel (you should be in the same directory where setup.py is). start up maya’s standalone interpreter by typing mayapy (or provide the full path to mayapy script if you do not have Maya’s bin directory on your PATH) at the prompt. now import setup.py as a module and run one of it’s tests:

import setup
setup.test_dynload_modules()

This will print out any compiled modules that do not work on your platform. This occurs because the flavor and/or distribution of Linux that you are running has different versions of certain system libraries than the one that Maya was compiled on. The easiest way to fix the problem is to create symbolic links from your existing libraries to those that Maya expects to find.

For example, in my case hashlib won’t import because it can’t find libssl.so.4. So, since I’m on a 64-bit version of linux, I check my /lib64/ ( on a 32 bit OS, check /lib/ )

cd /lib64
ls -la libssl*

I see the following returned:

-rwxr-xr-x 1 root root 302552 Nov 30  2006 libssl.so.0.9.8b
lrwxrwxrwx 1 root root     16 Jul 16  2007 libssl.so.6 -> libssl.so.0.9.8b

In my case, Maya expects libssl.so.4, but instead I have libssl.so.0.9.8b and a symbolic link libssl.so.6 pointing to libssl.so.0.9.8b. So, I have to create a symbolic link from the real library to the missing library:

sudo ln -s libssl.so.0.9.8b libssl.so.4

I’ve found that the same thing must sometimes be done for libcrypto as well.

userSetup files

Next, to avoid having to import pymel every time you startup, you can create a userSetup.py file and add the line:

from pymel.core import *

Script Editor

PyMEL includes a replacement for the script editor window that provides the option to translate all mel history into python. Currently this feature is beta and works only in versions beginning with Maya 8.5 SP1.

Warning

this feature is still considered experimental

The script editor is comprised of two files located in the pymel/tools/scriptEditor directory: scriptEditorPanel.mel and pymelScrollFieldReporter.py.

  1. Place the mel file into your scripts directory, and the python file into your Maya plugins directory.
  2. Open Maya, go-to Window –> Settings/Preferences –> Plug-in Manager and load pymelScrollFieldReporter. Be sure to also check “Auto Load” for this plugin.
  3. Next, open the Script Editor and go to History –> History Output –> Convert Mel to Python. Now all output will be reported in python, regardless of whether the input is mel or python.