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.