Your First Maya Python Plug-in

This topic will guide you through the creation and execution of your first Maya Python plug-in.

(Optional) Setting the Maya Plug-in Environment Variable

By default, Maya attempts to load the plug-ins placed in the following directory:

(Windows) C:/Users/<username>/Documents/maya/<version>/plug-ins
(Mac OS X)Library/Preferences/Autodesk/maya/<version>/plug-ins
(Linux) $MAYA_APP_DIR/maya/<version>/plug-ins

where <version> denotes the Maya version; for example: Maya2016.

There may be more than one default location from which Maya loads the plug-ins. See File path variables in the Environment Variables section of the Maya User Guide for more information. You can also type getenv MAYA_PLUG_IN_PATH in the command line for the list of directories that this environment variable is set to.

You can optionally define additional directories in the MAYA_PLUG_IN_PATH environment variable to instruct Maya to load plug-ins from these locations.

In Windows 7, open the Start menu, type "env" in the search box and press enter. In the User variables section, click on the "New" button, and enter "MAYA_PLUG_IN_PATH" as the variable name. Set the variable value to the path of your choosing, where you will later save your scripts. For example, the variable value "%USERPROFILE%\Documents\scripts" corresponds to the current user's My Documents\scripts directory. Multiple paths can be specified by separating these variable values with a semicolon ";".

When you launch Maya, the directories contained in the MAYA_PLUG_IN_PATH will appear as different sections under Window > Settings/Preferences > Plug-in Manager.

Writing a Python Plug-in using the Script Editor

The Python and MEL Script Editor window can be found under Window > General Editors > Script Editor. Python plug-ins can also be written in an external text editor of your choice, however we will pursue this topic using Maya's built-in interactive Script Editor.

In the Python tab of the Script Editor, paste the plug-in code below. This code creates a simple command which prints "Hello World!" out to the Script Editor output when it is invoked. Other sample Python plug-ins, including the ones below, can be found in the devkit/plug-ins/scripted folder of your Developer Kit installation (see Setting up your build environment: Windows environment (64-bit)). The plug-ins using the 2.0 API start with 'py', for example pyHelloWorldCmd.py. We describe the code structure of plug-ins in subsequent topics. For now, we will focus on executing our first plug-in:

Python API 2.0:

import sys
import maya.api.OpenMaya as om

def maya_useNewAPI():
	"""
	The presence of this function tells Maya that the plugin produces, and
	expects to be passed, objects created using the Maya Python API 2.0.
	"""
	pass


# command
class PyHelloWorldCmd(om.MPxCommand):
	kPluginCmdName = "pyHelloWorld"

	def __init__(self):
		om.MPxCommand.__init__(self)

	@staticmethod
	def cmdCreator():
		return PyHelloWorldCmd()

	def doIt(self, args):
		print "Hello World!"


# Initialize the plug-in
def initializePlugin(plugin):
	pluginFn = om.MFnPlugin(plugin)
	try:
		pluginFn.registerCommand(
			PyHelloWorldCmd.kPluginCmdName, PyHelloWorldCmd.cmdCreator
		)
	except:
		sys.stderr.write(
			"Failed to register command: %s\n" % PyHelloWorldCmd.kPluginCmdName
		)
		raise


# Uninitialize the plug-in
def uninitializePlugin(plugin):
	pluginFn = om.MFnPlugin(plugin)
	try:
		pluginFn.deregisterCommand(PyHelloWorldCmd.kPluginCmdName)
	except:
		sys.stderr.write(
			"Failed to unregister command: %s\n" % PyHelloWorldCmd.kPluginCmdName
		)
		raise

Python API 1.0:

import sys
import maya.OpenMaya as OpenMaya
import maya.OpenMayaMPx as OpenMayaMPx

# command
class HelloWorldCmd(OpenMayaMPx.MPxCommand):
	kPluginCmdName = "spHelloWorld"

	def __init__(self):
		OpenMayaMPx.MPxCommand.__init__(self)

	@staticmethod
	def cmdCreator():
		return OpenMayaMPx.asMPxPtr( HelloWorldCmd() )

	def doIt(self,argList):
		print "Hello World!"


# Initialize the script plug-in
def initializePlugin(plugin):
	pluginFn = OpenMayaMPx.MFnPlugin(plugin)
	try:
		pluginFn.registerCommand(
			HelloWorldCmd.kPluginCmdName, HelloWorldCmd.cmdCreator
		)
	except:
		sys.stderr.write(
			"Failed to register command: %s\n" % HelloWorldCmd.kPluginCmdName
		)
		raise

# Uninitialize the script plug-in
def uninitializePlugin(plugin):
	pluginFn = OpenMayaMPx.MFnPlugin(plugin)
	try:
		pluginFn.deregisterCommand(HelloWorldCmd.kPluginCmdName)
	except:
		sys.stderr.write(
			"Failed to unregister command: %s\n" % HelloWorldCmd.kPluginCmdName
		)
		raise

In the Script Editor window, select File > Save Script. Set the file name to myFirstPlugin.py (you may omit the .py extension - it will be appended automatically), and save the script in C:\Users\<username>\Documents\maya\<version>\plug-ins, or in one of the directories defined by your MAYA_PLUG_IN_PATH environment variable.

To verify that Maya has detected your newly saved script, access the Plug-in Manager window via Window > Settings/Preferences > Plug-in Manager, and press the "Refresh" button. Your plug-in file should appear here. Do not select any of the "Loaded" or "Auto load" checkboxes for now.

Loading your Python Plug-in

There are two ways to load you newly created plug-in into Maya:

Programmatically - In the Script Editor, delete our previous Python code. Now write the following lines of code and execute them using the blue "Play" button on the Script Editor toolbar.
```
import maya.cmds
maya.cmds.loadPlugin("myFirstPlugin.py")
```
Observe that if you go into the Plug-in Manager window, the plug-in's "Loaded" checkbox will now be checked.
Manually - In the Plug-in Manager window, you may check the "Loaded" and/or "Auto load" checkboxes. Selecting these will respectively load the plug-in, and ensure that the plug-in is automatically loaded when Maya is launched. Un-checking and re-checking the "Loaded" checkbox will reload your plug-in, which may be useful for testing and debugging your code.

Invoking your Python Plug-in

The plug-in we just wrote is a "Command" plug-in. That is to say, our plug-in defines a new command which outputs "Hello World!" when it is invoked. If our plug-in is properly loaded, then it should appear as a new MEL command, and should also appear as a new function within the maya.cmds Python module. This module defines all the available Maya Python commands (which is a subset of the available MEL commands). To invoke our command, execute the following code in the Script Editor:

import maya.cmds as cmds
cmds.spHelloWorld()

The Script Editor should display the following lines, which echo our commands as well as the "Hello World!" output.

import maya.cmds as cmds
cmds.spHelloWorld()
Hello World!

Congratulations! You have just run your first Maya Python plug-in!