Trac is being migrated to new services! Issues can be found in our new YouTrack instance and WIKI pages can be found on our website.

Help home > FAQ home

Scripting and Plugins

What is a plugin?

A plugin is an additional piece of software that, when loaded into the running Pidgin or Finch application, provides additional features and functionality. We support several types of plugins, as explained in the next question.

Where can I find Plugins?

A nice collection of plugins can be found on the ThirdPartyPlugins page.

What is the difference between plugin types?

There are a variety of plugin types that Pidgin, Finch, and libpurple support.

  • "core" (libpurple) plugin - This type of plugin is a generic plugin that has absolutely no UI code at all. It should work with any libpurple UI. Exceptions to this rule may arise if a particular UI doesn't provide implementations for certain things libpurple expects a UI to implement, such as the request API. This lack of implementation will be a problem only if the libpurple plugin requires it.
  • "GTK+" (Pidgin) plugin - This type of plugin will work only with Pidgin because it depends on the GTK+ user interface Pidgin supplies. This type of plugin has the ability to use anything libpurple provides as well as anything Pidgin provides. Furthermore, a Pidgin/GTK+ plugin may provide its own custom UI for configuration or other necessary dialogs by directly implementing them in GTK+.
  • "GNT" (Finch) plugin - This type of plugin will work only with Finch because it depends on the GNT user interface Finch supplies. This type of plugin has the ability to use anything libpurple provides as well as anything Finch provides. Furthermore, a Finch/GNT plugin may provide its own custom UI for configuration or other necessary dialogs by directly implementing them in GNT.
  • Loader plugins (sometimes called "lopl") - These are special libpurple plugins that are invisible--they don't appear in the plugins list in a libpurple UI. These plugins enable the loading of plugins written in other languages. Our Perl plugin support is provided via a loader plugin, as is our Tcl plugin support.
  • Protocol plugins (called "prpl") - These are special libpurple plugins that are invisible--they don't appear in the plugins list in a libpurple UI. They are what makes libpurple able to connect to so many networks. Each protocol plugin provides an implementation of a specific IM/chat network's protocol that libpurple can use. All protocol support in libpurple is provided via protocol plugins. As protocol plugins are libpurple plugins, they may not contain any UI code at all.

How do I use Perl scripts with Pidgin/Finch?

Save the Perl script to ~/.purple/plugins or $PREFIX/lib/purple and open the Plugins dialog. If the script is written correctly, it will appear in the list and you will be able to load it.

How do I compile a plugin? (UNIX-like platforms)

This is highly dependent on the plugin.

  • Many third-party plugins provide a configure script and will compile and install via the normal routine of running the configure script, then running the make command, then running make install.
    • For this to succeed, the development packages for Pidgin and libpurple must be installed.
      • If you installed from source, the necessary files are already present.
      • If you installed via a package, install the pidgin-dev or pidgin-devel and libpurple-dev or libpurple-devel packages as appropriate for your distribution or package provider. Consult your package manager's documentation.
    • Plugin authors should provide this information, if applicable to their plugin(s), on their website.
  • Some plugins that ship with Pidgin, Finch, and libpurple don't compile by default. To compile these plugins, change to the appropriate directory in the source tree. The directories you have to choose from are pidgin/plugins, libpurple/plugins, and finch/plugins. Once in that directory, run the command make filename.so, where filename is the name of the plugin. For example, the Offline Messaging plugin is called offlinemsg.c, so if you wanted to build that plugin, you would run make offlinemsg.so. To install and use the plugin, you can copy the .so file to ~/.purple/plugins (creating the directory if needed) or to $PREFIX/lib/purple-2 for libpurple plugins, $PREFIX/lib/pidgin/ for Pidgin plugins, or $PREFIX/lib/finch for Finch plugins.
  • Some third-party plugins rely on our build infrastructure, and will compile using the same instructions as our non-default plugins. Plugin authors should provide this information, if applicable to their plugin(s), on their site.

How do I compile a plugin? (Windows)

This section covers only building plugins included with our source distribution, as not everyone uses the same method to build a plugin on Windows. Please refer to those plugins' websites for information on building the plugins for Windows.

Read and correctly follow the instructions on BuildingWinPidgin. It is very important that you follow the instructions correctly, as a correctly configured build environment is absolutely REQUIRED for building a plugin to work.

Once the build environment is set up, build Pidgin:

~/pidgin $ make -f Makefile.mingw

Next, change to the appropriate plugins directory:

~/pidgin $ cd libpurple/plugins
### OR
~/pidgin $ cd pidgin/plugins

Once here, you can compile a specific plugin by running make -f Makefile.mingw filename.dll, where filename is the name of the plugin. For example, the Offline Messaging plugin is called offlinemsg.c, so to build this plugin you would issue the command make -f Makefile.mingw offlinemsg.dll.

Note that some third-party plugins rely on our build infrastructure and will build once you place the .c file in the appropriate plugins directory. Plugin authors should indicate this information, if applicable to their plugins, on their website.

Why doesn't my Perl plugin show up in the Plugins dialog?

Check if your Pidgin binary includes Perl support (Help -> Build Information).

You must also have a compatible Perl runtime installed. Perl micro versions are not backward compatible, so you need to use a matching "y" component in the x.y.z version string.

On Windows:

  • You can get a compatible Perl runtime from Strawberry Perl
  • You'll need to use the 32-bit version of Perl since Pidgin is a 32-bit application
  • Make sure the Perl installation's bin directory is in your PATH
  • For Pidgin 2.10.12 and newer, you need Perl 5.20.z
  • For Pidgin <= 2.10.11, you need Perl 5.10.z

First, download the test Perl plugin from the Perl Scripting HOWTO page in ~/.purple/plugins. Restart Pidgin and see if the plugin appears in the list as "Perl Test Plugin". If not, open the Debug window from the Help menu, and open the plugin list again. You should see if Pidgin picks up the plugin from the proper directory, and any errors while loading it.

Alternatively, you may want to make sure that the plugin passes a syntax check, by running perl -c -I<path to Pidgin's plugins/perl directory> plugin.pl.

If you wrote the plugin yourself, you have likely missed some important detail about implementation or need to update to the current Perl API, which has changed several times.

If you downloaded the plugin, it may be out of date due to Perl API changes. You may need to contact the author or visit the plugin's website for an update.

Where can I find documentation on writing plugins?

If you click the API link in the toolbar above, you will be taken to our doxygen-generated documentation. There is a Related Pages section in the documentation that contains a bunch of useful stuff, including a run-down of all our signals by category, a basic C plugin How-To which is slightly out of date but still a good starting point, and some useful notes on translations support for third-party plugins. There is also a How-To on writing Perl scripts, which is outdated as well. We have begun the work of migrating the C How-To to the wiki. We will be expanding it with more information.

Are there licensing restrictions on plugins?

Yes. Libpurple is released under a GPL license. Any derivative works must be released under a compatible license. The way that plugins work in Libpurple causes them to fall in the "derivative" category and consequently MUST be released under a GPL compatible license. To be clear, this requirement means that plugins that use libraries with incompatible licenses MUST NOT be distributed (even if they use dynamic linking).
The FSF maintains a FAQ about the GPL that contains answers to many common questions.
If you have any specific questions, feel free to send a message to the development mailing list.

Last modified 8 years ago Last modified on Sep 28, 2015, 1:45:51 PM
All information, including names and email addresses, entered onto this website or sent to mailing lists affiliated with this website will be public. Do not post confidential information, especially passwords!