Proposing an External pyRevit Extension
If your tool is too specific to be included in the main pyRevit toolset, you can still share it as an external extension so others can discover and install it.
See Extensions for how to structure and author the extension itself; this page covers listing it in the catalog.
Steps
- Structure your repository so the
.tabfolder is at the root. - Include an
extension.jsonfile in your repo. - Create a branch from the pyRevit repository.
- Navigate to
extensions/extensions.json. - Add your extension entry to the
"extensions"list. - Open a pull request against the
developbranch.
Example Entry
A typical entry in extensions/extensions.json looks like this:
{
"builtin": "False",
"type": "extension",
"rocket_mode_compatible": "True",
"name": "YourExtensionName",
"description": "Short description of what your extension does",
"author": "Your Name or Organization",
"author_profile": "https://github.com/your-profile",
"url": "https://github.com/yourname/your-extension.git",
"website": "https://your-project-website-or-repo",
"image": "",
"dependencies": []
}
Review Process
Once you submit the PR, we'll review your extension and its metadata against the acceptance criteria below. If everything checks out, we'll add it to the directory so others can easily find and use it. It's worth running through the list before you open your PR, since it's what we'll be doing too.
Acceptance Criteria
To keep the catalog safe and reliable for everyone, every listed extension needs to meet the requirements below. The recommended items aren't blockers, but they make your extension feel at home in pyRevit and may come up as review feedback.
Required
- Open source. The repository URL in
extensions.jsonmust be publicly accessible and contain the full source code of the extension. - Source for all compiled binaries. Any
.dllshipped in abin/folder must have its source available in the same repository (or a clearly linked one). Binary-only extensions can't be reviewed for security and won't be accepted. - Valid structure. As described in the steps above, the
.tabfolder sits at the repository root, and the bundle layout follows the conventions in Extensions (*.pushbutton,*.panel, etc.). extension.jsonmanifest. Include anextension.jsonat the extension root declaringname,description,author,url, anddependencies(an empty list if there are none).- Correct catalog entry. The entry in
extensions/extensions.jsonmust be complete and accurate. Setrocket_mode_compatibleto"True"only if you've verified the extension works in rocket mode. - License. The repository must include a license file.
- Working installation. The extension must install without errors via
pyrevit extend, then load without errors after starting Revit or reloading pyRevit on a supported Revit version. - English titles and tooltips. Provide
titleandtooltipinbundle.yamlwith at least anen_usentry.
Recommended
- Dark theme support. Provide an
icon.dark.pngalongside everyicon.png, andbackground_darkcolors for any*.panelbundle that sets a custombackground. - Additional languages. Where feasible, offer
titleandtooltipas locale maps (e.g.en_us,fr_fr,de_de) beyond English. - Revit version bounds. Declare
min_revit_version/max_revit_versioninbundle.yamlwhen the tool depends on version-specific API behavior. - Usage context. Set
contextinbundle.yamlso buttons are greyed out when they can't run (e.g.doc-project,selection), rather than failing at click time. - Accurate dependency lists. Keep the
dependenciesarray identical inextension.jsonand theextensions.jsonentry, listing any required library extensions (*.lib). - Documentation. Include a
READMEand, ideally, a*help.*file orhelp_urlinbundle.yamlso users can reach documentation from the tooltip. - No side effects on load.
startup.pyshould not make network calls, write outside the extension folder, or change the user's pyRevit configuration without disclosure.