Install with PortalΒΆ

desktop-entry-lib allows you to directly install a Desktop Entry using the DynamicLauncher Portal. This Portal should be working out of the box on any major Distro. You need jeepney installed to use the Portal. You also need a Icon and a ID.

First you need to load the Icon as bytes. It must be a png or jpeg no larger than 512x512, or an svg.

with open("/path/to/my/icon", "rb") as f:
    icon = f.read()

Now, you need to create the Entry that you want to install.

entry = desktop_entry_lib.DesktopEntry()
entry.Name.default_text = "My Name"
entry.desktop_id = "com.example.App.Entry"
entry.Exec = "my-app"

The desktop_id needs to start with the ID of your App e.g. If your AppID is com.example.App you can use com.example.App.Entry but not com.example.Entry. If you are not sure, just try any ID. You will get an error message that tells you what ID is allowed.

Now you just need to call install_with_portal() with a Window Identifier. and your Icon. If you don't have a Window Identifier, just use an empty string. If an error occurs, install_with_portal() will throw a InstallWithPortalError exception. If the User cancels the Installation, a InstallWithPortalsCanceled exception is thrown. If the DynamicLauncher Portal is not available, InstallWithPortalsNotAvailable is thrown. If everything worked, it returns a dict that contains the Name and the Icon.

try:
    entry.install_with_portal("", icon)
except desktop_entry_lib.InstallWithPortalsNotAvailable:
    print("The DynamicLauncher portal is not available")
except desktop_entry_lib.InstallWithPortalError as ex:
    print(ex.message)
except desktop_entry_lib.InstallWithPortalsCanceled:
    print("The user canceled the installation")

A dialog should appear, allowing the user to install the entry. install_with_portal() has the 2 Keywords arguments editable_name and editable_icon, which allows to control if the User can edit the Name/Icon in the dialog. These arguments are not guaranteed to work on every desktop.

You should also take a look at the complete example.