Python Environment¶

Explains the features and limitations of the ZBrush Python environment.

The ZBrush 2026.1.0 Python Runtime Environment is based on CPython 3.11.9 and offers largely the same experience as a standard CPython installation. It however differs in its usage and features from a common Python installation in a few important aspects, which are explained in the following sections.

Virtual Machine¶

The main difference between the ZBrush Python Virtual Machine (VM) and a standard CPython VM is that the ZBrush Python VM is embedded into the ZBrush application itself. This means that when you run a Python script or plugin in ZBrush, it is executed within the context of the ZBrush application, rather than in a separate Python interpreter process. Find below a summary of the most important differences which follow from this fact:

Note

See also Best Practices for the practical implications of these differences when writing scripts and plugins for ZBrush.

Difference	Description
Interpreter Persistence	The ZBrush Python VM is a persistent Python instance that runs as long as ZBrush is running, and is shared between all scripts and plugins the user might run. This means that any state you change in the Python environment (e.g., global variables, imported modules, installed packages) will persist between script executions and might affect other scripts.
Working Directory	The working directory of the ZBrush Python VM is always the ZBrush application directory (i.e., where `ZBrush.exe` or `ZBrushMac.app` is located). This differs from a common CPython instance, where the working directory is the directory where the executed script is located or where the Python interpreter was started.
Module Search Paths	Other than for a standard CPython instance, the directory of an executed script or plugin is not automatically added to the module search paths (i.e., `sys.path`) of the ZBrush Python VM. This impacts how you can import modules in your scripts. See Importing Libraries for more information.
VM Executable	The ZBrush Python VM is the ZBrush executable itself (i.e., `sys.executable` points to `ZBrush.exe` or `ZBrushMac.app`). This limits the usage of certain modules that expect `sys.executable` to point to a Python interpreter binary that understands Python-specific command line arguments. For example, invoking `subprocess.run([sys.executable, "my_script.py"], ...)` will not work as expected.
Stream Handler	The ZBrush Python VM uses a custom stream handler to redirect standard output and error streams to the ZBrush console. This means that you cannot easily overwrite the stream handlers as this will break the output redirection from and to the ZBrush console.

The following support limitations apply when using the ZBrush Python SDK:

The multiprocessing module is not supported.
The subprocess module is not supported, when used to invoke the ZBrush Python VM itself, e.g., subprocess.run([sys.executable, “my_script.py”], …). Other usages of the subprocess module are supported.
Most third-party libraries will work, but all third-party libraries are explicitly out of scope of support. This means that if you encounter issues with third-party packages, you must resolve them yourself or seek help from the package maintainers or community. We can only provide support for issues related to the ZBrush Python SDK itself. Third party libraries that attempt to spawn new Python processes (e.g., via multiprocessing or subprocess) will not work.

Environment Variables¶

ZBrush respects the following two environment variables to configure the Python environment:

PYTHONPATH¶

The PYTHONPATH variable is used to define additional module search paths for the ZBrush Python VM. It behaves largely the same way as in a standard CPython VM. I.e., you can place here libraries you want to import in your scripts without manipulating the default search paths.

Warning

Be careful on systems where multiple applications use the PYTHONPATH variable, as it might lead to Python version or package conflicts. Such environment can only contain libraries that are compatible with the Python version used by ZBrush.

Other than a standard CPython VM, ZBrush will also scan all PYTHONPATH directories for init.py files and execute them on startup. This allows for automatically adding ‘plugins’ to the palettes of ZBrush that load when ZBrush starts up. E.g., you could create directory structure as follows:

TimePlugin
├── init.py
└── README.md

Which is a ‘plugin’ that users can install by adding the TimePlugin directory to a directory in one of their PYTHONPATH paths. The init.py file could then contain code like this:

"""Implements a simple plugin that displays the current time in a dialog when a button is pressed.
"""
from zbrush import commands as zbc
from datetime import datetime

def show_time(sender: str) -> None:
    """Implements a button callback function that displays the current time when invoked.
    """
    zbc.message_ok(f"The current time is: {datetime.now().strftime('%H:%M:%S')}", "Current Time")

if __name__ == "__main__":
    # Add a 'Show Time' button directly to the ZScript palette.
    zbc.add_button("ZScript:Show Time", "Displays the current time in a dialog.", show_time)

ZBRUSH_PLUGIN_PATH¶

The ZBRUSH_PLUGIN_PATH variable is used to define additional plugin search paths for the ZBrush Python VM. It behaves mostly the same way as PYTHONPATH, but other than it, it will execute all *.py files found in the defined directories on startup.

Category	Option	Description
Query		The search does not support special search operators. Terms are joined by default with OR unless the AND join mode is enabled. Queries can contain search literals denoted by double quotes. E.g., `foo bar` would search for documents that contain `foo` and/or `bar` (depending on the selected join option). But `"foo bar"` would search for the exact phrase "foo bar". The search is case-insensitive. Note that search literals will always implicitly enable strict search mode, even when the user has selected fuzzy mode.
	/	Toggles the visibility of the facet selection panel.
	/	Toggles the visibility of this help panel.
	OR / AND	Toggles between joining search terms with a logical OR or AND. In OR mode, the search will return results that match any of the search terms, while in AND mode, it will only return results that match all of the search terms.
	/	Toggles between fuzzy and strict mode when searching. In fuzzy mode, the search is more lenient and may return more results, while in strict mode, the search is more exacting. Switching modes may affect the relevance of the results.
	/	Toggles between detailed and compact result views. The detailed view shows more information per search hit.
	/	Toggles sorting the search results by relevance only or by a combination of classification and relevance. When sorting by classification and relevance, results are grouped by their type (e.g., pages, classes, methods) and then sorted by relevance within each group.
Facets		Facets restrict the search to specific content types. You must have at least one facet enabled per facet group to see any results. Domain is the largest facet group, enabling or disabling whole groups of content types. Entities are the next level down, allowing you to search within specific types of content such as generic pages or a function definition. Contexts are the most granular level, allowing you to search within specific contexts of the selected entity such as a code block ot the name of an entity.
Domain	API	Enable matches within API documentation pages.
	Manuals	Enable matches within general documentation pages.
	Examples	Enable matches within example pages.
Entity	Page	Enable matches within a page body that are not one of the following entities.
	Classes	Enable matches within class definitions.
	Methods	Enable matches within class method definitions.
	Functions	Enable matches within module function definitions.
	Attributes	Enable matches within class or module attribute definitions.
Context	Paragraphs	Enable matches within normal text paragraphs of a page.
	Headings	Enable matches within the headings of a page.
	Code	Enable matches within code blocks of a page (e.g., in the Examples domain or code blocks embed elsewhere).
	Names	Enable matches within the names of API entities. This searches the plain names (`func`), not the qualified names (`foo.bar.func`).
	Signatures	Enable matches within the signatures of API entities. The signature is what is shown on top of the entity description, e.g., `foo.bar.func(a: int, b: str = "Hello") -> bool`. When you want to search for fully qualified names, you should enable this option and disable the "Names" option.
	Metadata	Enable matches within the metadata of entities.