IronPython scripts
Start with the short introduction to scripts at Create Your First Command
See Python Script Facilities for information about the script support module
Language Safe Code
If you are using unicode characters in your code e.g. __title__ = "测试包", you need to start the script with the line below and save the file in UTF-8 encoding.
Setting Script Metadata
pyRevit looks for certain global scope variables in each scripts that provide metadata about the script and follow the __<name>__ format.
It's preferred to use the Bundle Metadata files for this purpose. The convention described here is only for convenience when creating very simple IronPython scripts.
pyRevit reload is required for changes to take effect.
Title
Similar to Bundle Metadata
Button Title: When using the bundle name as the button name in Revit UI is not desired, or you want to add a newline character to the command name to better display the butonn name inside Revit UI Panel, you can define the __title__ variable in your script and set it to the desired button title.
__title__ = 'Test\\nBundle'
# title can also be in various locales
# pyRevit pulls the correct title based on Revit langauge
__title__ = {
"en_us": "Test Bundle",
"chinese_s": "测试包"
}
DocString (Tooltip)
Similar to Bundle Metadata
Button Tooltip: Tooltips are displayed similar to the other buttons in Revit interface. You can define the tooltip for a script using the doscstring at the top of the script or by explicitly defining __doc__ metadata variable.
# defining tooltip as the script docstring
"""You can place the docstring (tooltip) at the top of the script file.
This serves both as python docstring and also button tooltip in pyRevit.
You should use triple quotes for standard python docstrings."""
# defining tooltip by setting metadata variable
__doc__ = 'This is the text for the button tooltip associated with this script.'
# docstrings can also be in various locales
# pyRevit pulls the correct docstring based on Revit langauge
__doc__ = {
"en_us": "Create new patterns in Revit",
"chinese_s": "创建新模式"
}
Author
Similar to Bundle Metadata
Button Author/Creator: You can define the script author as shown below. This will show up on the button tooltip.
Help URL
Similar to Bundle Metadata
Button F1 Help URL: You can define the help URL of the script. When this is provided, hitting F1 button when hovering over the button will open this URL in the default browser.
# bundle help url
__helpurl__ = "https://www.youtube.com/watch?v=H7b8hjHbauE&t=8s&list=PLc_1PNcpnV57FWI6G8Cd09umHpSOzvamf"
# help url can also be in various locales
# pyRevit pulls the correct help url based on Revit langauge
__helpurl__ = {
"en_us": "https://www.youtube.com/watch?v=H7b8hjHbauE&t=8s&list=PLc_1PNcpnV57FWI6G8Cd09umHpSOzvamf",
"chinese_s": "https://www.youtube.com/watch?v=H7b8hjHbauE&t=8s&list=PLc_1PNcpnV57FWI6G8Cd09umHpSOzvamf"
}
Revit will also show a tip for this F1 action, at the bottom of the tooltip.

Supported Revit Versions
Similar to Bundle Metadata
You can specify the min and max Revit versions that support your script.
Beta Tools
Similar to Bundle Metadata
You can mark your script as beta. By default beta tools will not be loaded in the interface. This option helps you work on your tool in private and turn off beta only when it is tested and ready.
Button Highlighters
Similar to pyRevit Bundles
You can use provide highlighting directives inside the bundle metadata as well. Revit will highlight the button the tooltip in the interface.
Context Directives
You can define the required context for your script. See Bundle Context
IronPython Engine Configurations
Clean Engine: When pyRevit is in Rocket Mode (default), it caches the engines used to execute commands. This means that a module that is imported into your script (e.g. import os) will remain imported on the next executions and thus speeds up the tool execution. Set the engine to clean if this is causing issues for your tool. See Button Click Modes for manually requesting a new clean engine.
Full-Frame Engine: Full-Frame engines, contain all the frame stack information that is required for code inspection but they have a much higher memory footprint. pyRevit disables the full-frame by default. This setting might break some module (e.g. import requests). If that's the case, activate the full-frame in your code
Persistent Engine: To reduce the memory footprint, pyRevit clears the global scope of each script after execution. If you are leaving global objects in memory that are going to be used later (e.g. event handler functions, and non-modal windows), you need to activate the persistent engine flag. pyRevit will not clear the scope for the tools that need a persistent engine.
Engine Configurations in Bundle File
IronPython bundles can define the engine configurations inside the bundle metadata file as well.
See Bundle Metadata for more information on these files.
Shipped Packages
Packages listed here are shipped with pyRevit by default for convenience