Headless Maya Batch Rendering: Batch Licenses, mayapy, and Render-Farm Exit Codes

The scene renders on a workstation but fails on the farm

An artist clicks Render in Maya and the image sequence appears. The same scene submitted to a headless render node returns nothing, or the job exits without writing frames. The problem is usually not the renderer. It is the batch license token, a Python script running outside Maya's interpreter, or absolute file paths that break once the scene leaves the artist's machine.

This article covers how to run Maya headless with mayabatch and the Render executable, how to prepare scenes with mayapy and Python API 2.0, and how to verify a job before submitting a full sequence.

Batch licenses are separate from interactive licenses

mayabatch and Render check out a Maya batch license token, which is distinct from the interactive license used on an artist workstation. If the network license server is unreachable or all batch tokens are in use, the job can abort without writing an image. The failure may look silent because headless mode has no GUI to display a license dialog.

Check license availability on the render node before scaling. Run this from a shell on the render node:

lmutil lmstat -c [contact removed] -a

Run where: a shell on the render node or pipeline host. Required permissions: network access to the license server port and read access to the license configuration. Placeholders: replace 2083 with your Autodesk vendor daemon port and license-server.example.com with your license host. Expected check: the output lists Maya users and available batch licenses. Risk: no output or a connection error means the render node cannot reach the server; do not interpret silence as success.

Prepare scenes with mayapy, not system Python

Python API 2.0, available as maya.api.OpenMaya, must run inside Maya's Python interpreter. The standalone interpreter bundled with Maya is called mayapy. System Python does not include Maya modules, so a scene-preparation script that works in the Maya Script Editor will fail with ModuleNotFoundError under system Python.

Run scene preparation on a machine with mayapy on PATH:

mayapy /pipeline/prepare_scene.py /project/scenes/my_scene.ma

Run where: a render node or pipeline host with Maya installed. Required permissions: execute mayapy and read/write the scene file. Placeholders: /pipeline/prepare_scene.py is your preparation script and /project/scenes/my_scene.ma is the target scene. Expected check: mayapy exits with code 0 and the scene opens in Maya without missing nodes or attributes. Risk: using system Python or omitting mayapy causes import failures that are hard to debug in a batch log.

Submit the render and check the exit code

Use Render when the scene is already authored and you only need to write frames. Use mayabatch when you need to run MEL or Python commands before rendering. Both executables return an exit code: zero usually means success, non-zero means failure. Pipeline systems can use that code for retry logic.

Tool	Best for	Typical use
Render	Rendering an already-authored scene	Write image frames from a .ma or .mb file
mayabatch	Running commands before rendering	Execute MEL or Python, then render

Example single-frame test command:

Render -r arnold -s 1 -e 1 -rd /project/images -im test_frame my_scene.ma

Run where: a shell on the headless render node. Required permissions: execute the Render binary, read the scene, and write to the images directory. Placeholders: arnold is the renderer plugin name, /project/images is the output directory, test_frame is the image name prefix, and my_scene.ma is the scene file. Verify exact flags with Render -help on your installed Maya version, as options can differ between releases. Expected check: a file such as test_frame.0001.ext appears in /project/images. Risk: if the renderer plugin path is missing, Render reports that the renderer is not found. If the batch license checkout fails, the process may exit before writing anything.

Always run a one-frame batch render and compare it against the same frame rendered interactively. Headless mode lacks GPU viewport acceleration, so viewport-dependent effects can look different even when the batch render succeeds.

Limitations and pre-flight checklist

• Headless Maya has no GPU viewport acceleration. Compare batch output to interactive output before trusting the farm.
• Use relative paths or the Maya project workspace so texture and reference paths resolve on remote machines.
• Match MAYA_MODULE_PATH, PYTHONPATH, and plugin versions between artist workstations and render nodes.
• Verify the batch license token with lmutil before submitting more than a test frame.

Start with one frame on a headless node. Confirm the license checkout, the scene preparation, and the image output. Only then submit the full sequence.