External Tools

To add an external tool to PyDM, you will need to subclass the following base class and customize its methods:

class pydm.tools.ExternalTool(icon, name, group, author='', use_with_widgets=True, use_without_widget=True)[source]

Bases: object

PyDM base class for External Tools hook-up. This class offers a boilerplate for tools to be added to PyDM. Code available at PyDMApplication will automatically install the tool if available somewhere under PYDM_TOOLS_PATH or if explicitly installed.

  • icon (QIcon) – The icon to be used when rendering the menu. Use None for no Icon.

  • name (str) – The tool name. This must be unique across the combination group+name.

  • group (str) – The group in which this action must be inserted. This becomes a QMenu with the tool as an action inside.

  • author (str, optional) – This information is used to list the author name at the About screen.

  • use_with_widgets (bool) – Whether or not this action should be rendered at a Custom Context Menu for the PyDMWidgets. If False the tool will be available at the Main Window menu only and will receive as a parameter channels as None and sender as the main_window object.

  • use_without_widgets (bool) – Whether or not this action should be rendered at locations other than a widget Custom Context Menu.

call(channels, sender)[source]

This method is invoked when the tool is selected at the menu.

  • channels (list) – The list of channels in use at the widget.

  • sender (PyDMWidget) – The PyDMWidget or Main Window that triggered the action.


Recreate the tool based on the serialized information sent as parameter.


content (str) –


Retrieve basic information about the External Tool in a format that is parsed and used at the About screen.


Dictionary containing at least author, file, group and name of the External Tool.

Return type:



Verify if the ExternalTool is compatible with the given widget.


widget (QWidget) – The widget for which the ExternalTool is being assembled.


True if this ExternalTool is compatible with the widget, False otherwise.

Return type:



Serialize the information at this tool in order to make it possible to be added to another PyDM Application without user interference.

Return type:



from pydm.tools import ExternalTool
from pydm.utilities.iconfont import IconFont

class DummyTool(ExternalTool):

    def __init__(self):
        icon = IconFont().icon("cogs")
        name = "Dummy Tool"
        group = "Example"
        use_with_widgets = False

    def call(self, channels, sender):
        print("Called Dummy Tool from: {} with:".format(sender))
        print("Channels: ", channels)
        print("My info: ", self.get_info())

    def to_json(self):
        return ""

    def from_json(self, content):
        print("Received from_json: ", content)

    def get_info(self):
        ret = ExternalTool.get_info(self)
        ret.update({'file': __file__})
        return ret


There are two options for telling PyDM where your external tools are.

The first is the PYDM_TOOLS_PATH environment variable, which is an delimited list of paths to search for files that match the pattern *_tool.py. They can be in the provided path or any subdirectory of that path. On Linux, the delimiter is “:” whereas on Windows it is “;”.

Alternatively, for Python packages that contain external tools, an entrypoint may be used to locate the tool class.

Here is an example setup.py that could be used to locate a PyDM external tool in your own Python package:

from setuptools import setup, find_packages

    # ... other settings will go here
        "gui_scripts": ["my_package_gui=my_package.main:main"],
        "pydm.tool": [

This would assume that you have the following:

  1. A package named “my_package” with my_package/__init__.py and my_package/tool_name.py.

  2. In my_package/tool_name.py, a ToolClassName that inherits from ExternalTool.

After running pip install on the package, it should be readily available in PyDM.