How to extend PCManFM with custom actions

PCManFM is a free and open source file manager which is meant to be a lightweight alternative to applications like Thunar (the default Xfce4 file manager) or Nautilus/Files (the GNOME counterpart). Although designed to by easy on resources, PCManFM doesn’t lack functionalities, and it can be extended with custom actions.

In this tutorial we learn the syntax we can use to define custom actions and how to use them to extend PCManFM functionalities.

In this tutorial you will learn:

  • How to install pcmanfm on some of the most used Linux distributions
  • How to define a custom action
  • How to check the mime-type of a file
How to extend pcmanfm with custom actions
How to extend PCManFM with custom actions
Software requirements and conventions used
Category Requirements, Conventions or Software Version Used
System Distribution independent
Software pcmanfm
Other Administrative privileges to install PCManFM
Conventions # – requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command $ – requires given linux-commands to be executed as a regular non-privileged user


PCManFM is available in the official repositories of some of the most used Linux distributions, therefore can be easily installed by using their respective package managers. To install the application on Fedora, for example, we run the following command:

$ sudo dnf install pcmanfm

To install the “pcmanfm” package on Debian, Ubuntu, or generally every other Debian-based distribution, we can use apt:

$ sudo apt install pcmanfm  

On Archlinux, the most famous Linux rolling-release distribution, we can install PCManFM by using the pacman file manager:

$ sudo pacman -Sy pcmanfm

Introducing custom actions

PCManFM can be extended via “custom actions”, which, on the appropriate cases, can be accessed in the context menu of the application. They are quite easy to write, since they follow the Desktop Entry Specification. Custom actions, and the conditions for their applications (e.g. on what files they should be applied, for example) are defined in files with the .desktop extension, placed under the ~/.local/share/file-manager/actions directory.

Our first custom action

Nothing better than doing something to learn how it works and the basic concepts behind it, so let’s write our first custom action. For the sake of this tutorial, we will write an action which will let us convert .epub files into the .kepub format. For those of you who are not familiar with ebooks, Epub is the standard and most used electronic book format, readable by almost all readers except Kindles, while “kepub” is an extension designed by Kobo, to be used on their devices for added functionalities.

To perform the conversion we will make use of a small utility written in Go, called kepubify, so as a first thing, we need to install it. We can do it by running the command below:

$ go install

Defining the action

We define our custom action by writing the lines you can see below in the ~/.local/share/file-manager/actions/kepubify.desktop file (the name is completely arbitrary). Let’s take a look at the definition, and then discuss its components:

[Desktop Entry]

[X-Action-Profile epub_to_kepub]
Exec=/home/egdoc/go/bin/kepubify %f

First off all, you can see we defined generic information about the action inside the [Desktop Entry] stanza. Inside the stanza we used the Type key, and assigned the “Action” value to it: that is precisely how we specify we are defining a custom action.

We than used the Name key to specify a label for the action: this is very important and should reflect in the most clear manner the purpose of the action, since is what the user will see in the file manager context menu.

The Profiles key is used to specify the list of the profiles associated with the action. We can use multiple profiles for each action, so for example, to let the action change its behavior depending on what type of files it is called on. When multiple profiles Id are used, they must be separated by a ; (semi-colon). Our action has only one profile, which we identify as “epub_to_kepub”. Each profile is defined in its own dedicated section.

Defining a profile

Each profile related to an action is defined in the [X-Action-Profile <profile-id>] stanza. In the example above, we used two keys to define the profile associated to our action.

The first key, Mimetypes, as you can imagine, is used to provide the (semi-colon separated) list of mime-types the action should be applied to. A mime-type is nothing more than a label which used to identify a specific kind of data/file. Our action context-menu entry will appear only when we right-click on a file with one of the specified mime-type.

How can we find the exact mime type for a file? When working from the command line, we can use the file utility together with the --mime-type option. Here is what the command returns when an epub file is passed as argument:

$ file --mime-type "The Robots Of Dawn - Isaac Asimov.epub"
The Robots Of Dawn - Isaac Asimov.epub: application/epub+zip

The application/epub+zip mime type is indeed what we used in our profile, together with inode/directory, which is the mime-type associated to directories. We used both mime-types since the kepubify utility accepts either a file or a directory as argument. When an epub file is passed as argument, the application converts it and produces a file with the same name, but with the epub.kepub extension. When a directory is passed as argument, instead, all the epubs contained in it are converted; the converted files are placed in a directory named by adding the _converted string to the original directory name.

In the a profile definition, the exec key is crucial: it is with this key that we specify the command which should be executed when the user clicks on the action entry in the file manager context menu. Parameters can be passed in the value of the key: they are substituted at runtime. This is exactly how we reference the file on which the user performed the right-click, which must passed as argument to kepubify. In this case we used the %f parameter, which is always substituted by the name of the first selected file.

In the table below, you can see some other parameters and their description. For the complete list you can consult the Desktop Entry Specification:

Parameter Description
%f The name of the first selected file
%F The space-separated list of selected item names: this is basically the plural form of “%f”
%u The URI (Uniform Resource Identifier) of the first selected item
%U The space separated list of the selected items URIs
%c The selected items count

Testing our custom action

Once our action is ready, we can test it. To do so, we may want to launch PCManFM from a terminal emulator, so to visualize all possible errors generated when the action is executed. For PCManFM to “see” a new action it must always be restarted. Here is how the entry for our custom action appears in the context menu when we right-click on an epub file:

The context menu entry for our custom action
The context menu entry for our custom action

Closing thoughts

In this tutorial we learned the basics of how to define and use a custom action to expand the functionalities of the PCManFM file manager. We learned what are some of the keys and parameters we can use in the action definition; in the process, we also learned what are mime/types, and how we can check the mime-type of a file on Linux.

Comments and Discussions
Linux Forum