Skip to content

Using Plugins

Jump to bottom
Hiromichi Yokoyama edited this page Aug 5, 2026 · 2 revisions

Using Plugins

This page is for end users who want to install, manage, and use MoleditPy plugins. If you want to write a plugin, see docs/PLUGIN_DEVELOPMENT_MANUAL_V4.md in the main app repository instead — this page deliberately does not duplicate the plugin-authoring API.

1. What a plugin is

A MoleditPy plugin is a single Python file (or a small folder/zip package) placed in your personal plugin directory. On load, MoleditPy executes it and, depending on which entry point it defines, the plugin can add menu items, export/analysis actions, file openers for new extensions, 3D rendering styles, toolbar buttons, or run automatically on startup. Plugins have full access to the running application (the current molecule, the 2D scene, the 3D viewer) — there is no sandboxing, so only install plugins from sources you trust (see Safe Mode below for how to recover if one misbehaves).

2. Where plugins live

Your plugin folder is:

  • Windows: C:\Users\<you>\.moleditpy\plugins\
  • macOS/Linux: ~/.moleditpy/plugins/

(plugins/plugin_manager.py: self.plugin_dir = os.path.join(os.path.expanduser("~"), ".moleditpy", "plugins").) The folder is created automatically the first time it's needed. Each plugin is either:

  • a single .py file directly inside plugins/, or
  • a subfolder containing an __init__.py (a "package" plugin — several of the larger official plugins, e.g. ORCA Result Analyzer, ship this way), or
  • initially a .zip that gets extracted into a subfolder on install.

3. The Plugin Manager (Plugin ▸ Plugin Manager...)

Every plugin action starts from the Plugin menu in the main window. Plugin ▸ Plugin Manager... opens a dialog listing every discovered plugin in a table: Status, Name, Version, Author, Location (path relative to your plugin folder), Description.

  • Status is color-coded: green Loaded (working normally), gray No Entry Point (the file has none of initialize()/run()/autorun() — nothing happened), or red Error (Init): ... / Error (Autorun): ... (the plugin raised an exception while starting up; the message is shown right there in the table, and the same exception is logged — see Troubleshooting for where to find full detail).
  • Reload Plugins — re-scans the plugin folder and re-executes everything from scratch, without restarting MoleditPy. Use this after manually editing or dropping in a plugin file.
  • Open Plugin Folder — opens ~/.moleditpy/plugins/ in your OS file browser.
  • Remove Plugin — select a row and click this to delete that plugin's file (or, for a package plugin, its entire folder) after a confirmation prompt. This is permanent.
  • Explore Plugins Online — opens the official Plugin Explorer in your browser, where you can browse the full catalogue and download .py/.zip files to install manually.
  • Double-clicking a row shows the plugin's full metadata (name/version/author/status/location/description) in a message box.

Installing by drag-and-drop

The Plugin Manager window itself accepts drag-and-drop: drop a .py file, a .zip archive, or a folder (or its __init__.py) onto the window, confirm the name/author/version/description/SHA-256 shown in the prompt, and it's copied into your plugin folder and loaded on the next reload.

4. Installing plugins another way: --install-plugin

You can also install a plugin from the command line without opening the GUI at all:

moleditpy --install-plugin path/to/plugin.py
moleditpy --install-plugin path/to/plugin.zip
moleditpy --install-plugin path/to/plugin_folder/

This prints the same name/author/version/description/SHA-256 summary and asks for a y confirmation in the terminal before copying the file(s) into ~/.moleditpy/plugins/. See Command-Line Options for the full flag reference.

5. Safe Mode — recovering from a broken plugin

If a plugin crashes MoleditPy on startup, or you just want to rule plugins in or out while debugging, launch with:

moleditpy --safe

This skips plugin discovery entirely — plugin_manager is left None, so no plugin file is even read. Plugin ▸ Plugin Manager... in this mode shows only an informational message ("Plugins are disabled (safe mode)") instead of the plugin table. Once you've identified and removed/fixed the offending plugin, launch normally again.

6. Uninstalling / disabling a plugin

There is no separate "disable" toggle — a plugin is either present in your plugin folder (and therefore loaded) or it isn't. To remove one:

  • Use Remove Plugin in the Plugin Manager (deletes the file/folder for you), or
  • Manually delete the .py file or folder from ~/.moleditpy/plugins/ and click Reload Plugins (or restart MoleditPy).

7. The official plugin collection

MoleditPy's official plugins live in a separate repository, moleditpy-plugins, whose REGISTRY/plugins.json file is the authoritative index the Plugin Explorer and Plugin Installer plugin both read. Each registry entry records the plugin's id, display name, current version, author, one-line description, tag(s), Python-package dependencies, a downloadUrl (either a raw file inside the moleditpy-plugins repo, or a release asset on the plugin's own standalone repository for larger plugins), supported_python_version, and supported_os.

Two ways to get plugins from this collection:

  1. Plugin Explorer (browser) — https://hiroyokoyama.github.io/moleditpy-plugins/explorer/, reachable directly from the Plugin Manager's Explore Plugins Online button. Browse by tag/description, download the .py/.zip, then drag it onto the Plugin Manager window or use --install-plugin.
  2. Plugin Installer plugin — itself one of the official plugins (see the plugins wiki); once installed, Plugin ▸ Plugin Installer... lets you check for updates and install/update plugins from inside MoleditPy, without leaving the app. It fetches the same plugins.json registry, compares your installed versions, verifies every download's SHA-256 against the registry before installing (a mismatch hard-blocks the install), and only ever fetches over http/https.

For the full list of official plugins — what each one does, where it appears in the menus, and its requirements — see the moleditpy-plugins wiki.

8. A note on trust

Plugins run with the same privileges as MoleditPy itself and have no sandboxing — a plugin can read/write files, make network requests, or (in the extreme case of something like the Python Console plugin) execute arbitrary code you type. Only install plugins from sources you trust: the official collection above, or a plugin repository/author you've independently vetted. If you ever need to rule plugins out while diagnosing a problem, --safe mode (§5) is the fastest way to confirm whether an issue is plugin-related.

9. See also

Clone this wiki locally