This post is a follow-up on the previous post here.

Installing Eclipse & Pydev

Note: On Windows: depending on whether you are on a 64 or 32 bit machine, make sure you install the correct version of Java and Eclipse.

Install Java on your machine if it isn’t yet done http://www.java.com/
http://www.java.com/en/download/ie_manual.jsp?locale=en&host=www.java.com:80
Go to http://www.eclipse.org/downloads/ and then click ‘Eclipse Packages'

Choose any of the last ‘Packages’ version. It is not really important which one you download, could be the Java, Classic or C++ -it does not yet matter. Personally, I have chosen the C/C++ package and combined it later with the Java and PHP packages. These packages are ZIP files, so you can uncompress them on top of a previous one if you want.
Once installed, Start Eclipse and choose a workspace folder (your favorite place for Maya Python projects).
After Eclipse have fully started, go into -> Help -> Install New Softwares
Click on the ‘Add…’ button and fill the form with ‘Name=PyDev – Location=http://pydev.org/updates’
After you accepted the EULA and legal stuff, this should bring PyDev and PyDev Mylyn Integration (optional) into the list. Select them to install them.
Restart Eclipse

You are almost ready!

Configuring Eclipse

You only need to do this section if you wish to execute a standard Python application or a Maya Standalone application. If you only want to debug Maya Python scripts and Maya plug-ins, feel free to skip these steps.

Start Eclipse
Go into -> Window -> Preferences
Go into -> PyDev -> Interpreter – Python
- Python Interpreters -> New…
  - Interpreter Name = Python Maya
  - Interpreter Executable = ‘C:\Program Files\Autodesk\Maya2013\bin\mayapy.exe’
Accept all proposed path and include both paths below
- ‘C:\Program Files\Eclipse\plugins\org.python.pydev_2.6.0.2012062818\pysrc’
- ‘C:\Program Files\Autodesk\Maya2013\bin\python26.zip’

If you also want to configure another interpreter for a standard Python application and have Python installed already, do so now by adding a second interpreter configuration. You can add as many as you want.

Note the '2.6.0.2012062818' key in red above is changing depending of the Pydev version and it is important that you update it if you using a different version in future.

Preparing debugger scripts for Maya

Copy the attached Python script (debugmaya.py) into ‘C:\Users\<my profile>\Documents\maya\scripts’

IMPORTANT: Modify the path in the .py script to reflect the location where you have installed Eclipse (see line #18)

Copy the attached MEL script (scriptEditorPanel.mel) into ‘C:\Users\<profile>\Documents\maya\2013-x64\prefs\scripts’
Copy the attached image (debug.png) into ‘C:\Users\<profile>\Documents\maya\2013-x64\prefs\icons’

You are now ready! You can start Maya

NOTE: The paths mentioned above are for a Windows 64 bit machine. If you are running on a win32 machine, please adjust the path accordingly.

NOTE: For other platforms, the procedure is the same excepted for the paths mentioned above.

Let’s debug now

First be aware that you can debug both Maya Python scripts, Maya Python API plug-ins, and PyMel scripts, running inside Maya or in standalone mode.

Standalone application

Start Eclipse
Create a new project -> File -> New -> Pydev Project (if you can’t see it, then go to -> File -> New -> Project… then expand the Pydev folder, select ‘Pydev Project’, and click ‘Next’)
- Give a ‘Project name’
- Select
  - Project type = Python
  - Grammar Version = 2.6
  - Interpreter = Python Maya
- Note: If you get the ‘Open Associated Perspective?’ dialogue box, choose ‘Yes’
- Finish
Expand your project node in the Pydev Package Explorer window
Select the ‘src’ node, right-click -> New -> Pydev Module
- Give a ‘Name’ to your file (no extension)
- Select Template = ‘Module: Main’
- Finish
Modify the code to do something using Maya
- Use the helloworld.py sample from ‘C:\Program Files\Autodesk\Maya2013\devkit\applications\scripted’

You are ready to run or debug your code now

Note: There is nothing different to debug a standard Python application here. Whether you continue using the mayapy.exe or you switch to another interpreter. Eclipse can manage several Run/Debug configurations. See Eclipse documentation for more details.

Maya Python script (and PyMel)

This time it is a bit more complicated. Since Maya scripts are running inside Maya, we cannot launch mayapy.exe and expect to see maya.exe executing our script. Instead, we need to use the remote debugging feature of Eclipse/PyDev. What is Remote Debugging? In theory this feature is made to debug Python application running on a different machine than yours. While it is possible to do this as well with Maya Python, we are only interested to run it on the same machine at this time. This is to simplify the configuration. However, remember you can debug a script running in a Maya session running on another machine than yours. How cool is that? ;)

Anyway, let’s rock into our local debug Maya script debug session now. First, you remember how we had to install a script called ‘debugmaya.py’ during install time; this script will be used to connect Maya to the Eclipse Python remote debugger server. This script will ‘alert’ Eclipse that someone is executing some Python code and that we want to pass control to the Eclipse debugger. How to do this?

In Eclipse, switch to the debug perspective
(see -> Window -> Open Perspective -> Others… if you haven’t configured your favorites yet)
You should now see 2 buttons in the Eclipse toolbar:

A red square P button with a tooltip saying ‘Pydev: stop the debugger server’
A green bug P button with a tooltip saying ‘Pydev: start the pydev server’

Click on the ‘green bug P’ button
- On the ‘Console’ panel, you should now read ‘Debug Server at port: 5678’
- You should also see a debugger instance in the ‘Debug’ panel
Now the remote debugger is started, you can now start Maya
Open the Maya Script Editor and select a Python tab and write the following code as an example (or any code you’d like to debug)
- import sys
- print sys.path
Launch the debugger using the new ‘Debug’ button in the Script Editor (near the ‘Execute All’ button)

If everything was configured properly, you should see a few lines of text displayed in the Maya history pane, after that it looks like Maya has frozen but don’t panic, switch to Eclipse and see that Eclipse is pausing on a line saying:
- pydevd.settrace()
- This is the ‘alert’ signal from the remote application to the debugger. This leaves you a chance to prepare your debugging session before any code is executed. For example, you can set breakpoints in your code.
However, if you pay attention to the Maya history pane and the debugger panel, you’ll notice that the Pydev debugger tells you two things:
- Pydev debugger – <module> [<maya console>:NN]
- Maya console – “# pydev debugger: Unable to find real location for: <maya console>”
This is because the code which is in the Maya Script Editor has no physical file, and Pydev needs a file to retrieve the code for the debugger.

Go into your ‘C:\Users\<profile>\Documents\maya\2013-x64\scripts’, you should find a file named ‘__debug.py’. Drag and drop it into Eclipse. You should see the code you put into your Maya Python tab in the Script Editor. Now, in the left grayed margin either dbl-click or right-click to add a breakpoint on the print statement and press F8 to resume execution. The debugger should now stop right there, and now you have full access to your Maya/Python environments for debugging purposes.

You can now debug a Maya script as well as a PyMel script.

Maya Python plug-ins

Almost the same as a ‘Python Script’, the only differences are:

You load/unload plug-ins as any other plug-ins
You need to modify your plug-in script and add 2 lines at the top of the file

import debugmaya
debugmaya.startDebug()

If your debugger is already started, skip the next 3 steps and go directly into Maya

In Eclipse, switch to the debug perspective
(see -> Window -> Open Perspective -> Others… if you haven’t configured your favorites yet)
You should now see 2 buttons in the Eclipse toolbar:

A red square P button with a tooltip saying ‘Pydev: stop the debugger server’
A green bug P button with a tooltip saying ‘Pydev: start the pydev server’

Click on the ‘green bug P’ button
- On the ‘Console’ panel, you should now read ‘Debug Server at port: 5678’
- You should also see a debugger instance in the ‘Debug’ panel
Now the remote debugger is started, you can now start Maya
Go into the Plug-in Manager and load your Python scripted plug-in (I used the sineNode.py sample from the devkit folder)
Switch to Eclipse and see that Eclipse is pausing on the same line we described in the previous chapter.
Load your plug-in code into Eclipse and put breakpoints in initializePlugin() and in the sineNode.__init__() function. Press F8 to resume.
The debugger should stop immediately into initializePlugin() at the position you set the breakpoint. Press F8 again to resume execution.
Open the Script Editor, and in a MEL tab execute the following code

createNode “spSineNode”

The debugger should stop into sineNode.__init__() at the position you set the breakpoint. Press F8 again to resume execution.

In the Plug-in Manager, unload and load the Python scripted plug-in again, and see the debugger stopping again and again at your breakpoints

You can now debug Maya scripted plug-ins.

Advanced concepts

import & reload()

One important concept in Python is that import is executed only once. If you modify your code, you need to use the function reload() to force Maya to refresh the code changes. The debugmaya.py comes with an ImporterController which will take care of cleaning your Python environment so you do not have to care about this at all. However, you should be aware of what is done in the background. When you load a Python module, Python keeps an internal reference in a dictionary to avoid having to reload the same file definition multiple time. While it is good for performance and cross references, it is a disaster for someone who wants to debug the code, because it would mean to restart the application each time. To avoid this problem, the debugger creates a singleton instance of the controller and the controller makes a copy of the references dictionary. Then it replaces the built-in import function. From there any new imported modules would be reloaded each time when requested, but not the ones which were already loaded before the debugger started.

Debugging Python Maya native files

All Python Maya native files are zipped in the Python26.zip file. If you want to step through that code you need to either modify PyDev to extract the file on the fly, or you may explode Python26.zip file in ‘C:\Users\<profile>\Documents\maya\2013-x64\scripts’. Both solution will work. But I do recommend to do this only when you need to debug Python native files and only temporarily.

Will I be able to step-in Maya Python function and API?

No, you can only step through your own code. Maya functions and API are almost all written in C/C++. Unless a Maya component was written in Python language and exposed in a physical file, you wouldn’t be able to step through that code.

Can this solution be used in previous releases of Maya?

Yes, absolutely. All Maya versions with Python support can use this technique and add debugging support to Python. That includes releases starting from Maya 8.5.