Question
Maya Project Resolution Across GUI and Headless Launch Modes
Mira Byte
0 reputation · 27 Sept 2023, 06:43 UTC
98.1K views1
Loading…
0 reputation · 27 Sept 2023, 06:43 UTC
Maya resolves relative texture, cache, and reference paths against the active project directory defined by workspace.mel, but that directory is an implicit launch-mode state rather than a scene property. In an interactive desktop session, Maya often inherits the last-used project or prompts the user to select one, which can mask missing project configuration. In headless or render-farm contexts, such as mayabatch or Render, Maya may instead default to a generic project or the user’s home directory when no project is explicitly supplied.
The goal is to make a scene authored locally resolve identically in production without relying on interactive prompts. While the -project command-line flag and the MAYA_PROJECT environment variable are documented for explicit selection, Maya does not guarantee a single deterministic precedence order across GUI, batch, and render-launch modes, leaving behavior version- and platform-sensitive. Additionally, overrides made through the File Path Editor or the workspace command are not automatically serialized with the scene.
Which launch-time mechanism should be treated as authoritative when both MAYA_PROJECT and -project are present in a headless render job? Is there a supported way to lock the project directory into the scene so batch and render launches cannot silently fall back to a default? Do workspace command path overrides persist across launch modes, or must the project be re-established in every environment?
33775 reputation · 27 Sept 2023, 10:31 UTC
Treat the -project command-line flag as authoritative over MAYA_PROJECT in headless mayabatch and Render launches; explicit CLI arguments win over environment variables.
There is no supported way to lock the project directory into the scene file itself. Maya does not serialize the active project as a scene property in .ma or .mb, so the project must be established at launch time on every machine.
Workspace path overrides made through the workspace command or File Path Editor are stored in the project's workspace.mel, not in the scene. They apply only when that project directory is active, so they must be shared or re-established in every environment.
The core precedence rule—CLI -project beats MAYA_PROJECT—is the expected behavior for explicit launch arguments. However, Maya's fallback when neither is set, and its environment-variable handling, can vary by version and platform. Treat the precedence as reliable for explicit arguments, but verify the default fallback on your exact Maya build and renderer before relying on it in production.
A scene-level lock is not available. Workarounds such as embedding a scriptNode or scene callback to force workspace -open on load are unsupported and can introduce ordering or security issues; they should not be treated as a native lock.
maya-project /absolute/path/to/project explicitly in every headless launch command (both mayabatch and Render submissions).MAYA_PROJECT as a fallback for tools that do not expose the flag, but do not rely on it when -project is present.workspace.mel—is available on all render nodes.workspace -query -directory.Confirm precedence by comparing a launch with both variables set:
MAYA_PROJECT=/other/path mayabatch -project /path/to/project -file scene.maThen query the active directory inside the batch session to confirm it resolves to /path/to/project. Inspect the project directory for workspace.mel to confirm path overrides live at the project level, not in the scene.
Use comments to ask for clarification. Post a solution as an answer.
No question comments on this page.