This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Opens URL or file in user preferred application (xdg-open replacement).

Project Description

Python xdg-open (from xdg-utils) clone. Basically determines how to open and then opens given URL using system desktop files. It features customizable search order, custom mime to application call or to desktop file mappings and proper opening of multiple files. It also supports list files (like defaults.list), so it should work as expected out of the box with the default config.

Motivation for this is to provide file opener which works well without a popular desktop environment and still supports Desktop Entry Specification. Also it’s good to provide something which doesn’t have plethora of escaping or other input related bugs, e.g. xdg-open: be more paranoid in escaping. This is much easier and cleaner to achieve in Python than in Bash.

Example config file:

# Example config file, by default it should be located at:
# ~/.config/pyxdg-open/pyxdg-open.conf
# Paths where to search for desktop files in order of preference. It's a comma
# separated list.
desktop_file_paths = ~/.local/share/applications/,

# List files under desktop_file_paths which are first searched for desktop
# files. If this is empty no list files are used.
list_files = mimeapps.list,

# If default terminal emulator is not specified then first desktop file with
# TerminalEmulator as Category will be used.
#default_terminal_emulator = urxvtc

# Default search order. This means, first use list_files to find the appropriate
# desktop file and if not found, proceed to searching desktop files from desktop
# file paths.
search_order = list_files,

# An example of a custom search which can be added to the 'search_order' list,
# in this case, with name 'my_own_mappings'.
# Matching can be done with either mime type or file name ending. Mime type can
# be either full "type/subtype", or partial "type/" or "/subtype".
# Target can be either a command to which file name is appended before
# executing, or relative, or absolute path to a desktop file. Relative paths are
# interpreted to be relative to given desktop_file_paths.
# There's a special command '!bashwrap' which wraps following executable with
# bash, for more information see:
# A command target supports also Desktop file specifiactions Exec value field
# keys "%f", "%F", "%u" and "%U". If no field key is given "%F" is appended to
# the command by default.
#application/pdf = zathura
#video/          = vlc %U
#audio/          = vlc %U
#rar             = file-roller
#text/plain      = !bashwrap vim
#tar.gz          = /tmp/some_app.desktop
#inode/directory = urxvtc.desktop

´search_order´ defines the order of desktop file searches. By default the desktop files are first searched from the list files located in the ´desktop_file_paths´ (´list_files´ must be defined). Second the desktop files are searched normally from the defined ´desktop_file_paths´.

pyxdg-open also support mimi like custom configs which can be added to the ´search_order´ list.

If ´desktop_file_paths´ are searched for the desktop file then the first desktop file which has the matching mime type listed is selected. If there are many desktop files which match certain mime type and one desktop file is preferred, then the option is to add the mime type, desktop file pair to mimeapps.list or defaults.list file. Another way is to just add own custom mappings to the config file as seen from the example and add this sections name as first in the ´search_order´ list.


Print all found desktop files, which open PDF files without really opening anything. Useful for finding all possible desktop files, in this case for PDF:

$ pyxdg-open --dryrun --print-found some.pdf
Found desktop files:
/usr/share/applications/zathura.desktop [list_files]
/usr/share/applications/zathura.desktop [desktop_file_paths]
/home/wor/.local/share/applications/wine-extension-pdf.desktop [desktop_file_paths]
/usr/share/applications/xpdf.desktop [desktop_file_paths]
/usr/share/applications/zathura-pdf-poppler.desktop [desktop_file_paths]
/usr/share/applications/gimp.desktop [desktop_file_paths]

Let’s say that I have following in my config file:

search_order = my_own_mappings,

application/pdf = zathura.desktop
audio/          = vlc.desktop

Now running following runs correctly vlc with two parameters, so that both audio tracks end up in the vlc playlist. This is because default ´vlc.desktop´ file has ´%U´ in the Exec key value. If this had been, for example, ´%u´ or ´%f´, two instances of vlc would be launched simultaneously playing ´track01.mp3´ and ´track02.mp3´:

$ pyxdg-open -v1 --dryrun track01.mp3 track02.mp3
INFO:run_exec:613: Calling exec string: /usr/bin/vlc track01.mp3 track02.mp3

As ´zathura.desktop´ contains ´%f´ in the Exec string, only one file is accepted and pyxdg-open launches two instances:

$ pyxdg-open -v1 --dryrun test0.pdf test1.pdf
INFO:run_exec:613: Calling exec string: zathura /tmp/test0.pdf
INFO:run_exec:613: Calling exec string: zathura /tmp/test1.pdf

This also works correctly with following, as can be seen:

$ pyxdg-open -v1 --dryrun test0.pdf test1.pdf audio.mp3 audio.flac
INFO:run_exec:613: Calling exec string: /usr/bin/vlc audio.mp3 audio.flac
INFO:run_exec:613: Calling exec string: zathura /tmp/test0.pdf
INFO:run_exec:613: Calling exec string: zathura /tmp/test1.pdf

Easy install

Example of a simple user install:

python3 install --exec_name="xdg-open" --user

The executable console script name can be controlled with the ´–exec_name=´ argument. The default is ´pyxdg-open´. The executable script in this example is placed in ´$HOME/.local/bin´ which can be added to the PATH variable if needed. This also installs needed dependencies.

Archlinux PKGBUILD

PKGBUILD files for pyxdg-open and it’s dependencies can be found from my abs-repo: pyxdg-open-git and python-desktop-file-parser-git

By default the pyxdg-open-git conflicts with xdg-utils as it uses –exec_name=´xdg-open´. The abs repo also contains a PKGBUILD for xdg-utils which does not have ´xdg-open´: xdg-utils-without-open


Optional Dependencies

At the moment pyxdg-open works better with ´python-magic´ than, with the default python mimetypes library which is used only if ´python-magic´ is not found.


  • Document differences to similar programs
  • Read desktop cache files
  • Add missing xdg-open functionality
Release History

Release History

This version
History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
pyxdg_open-0.2.1-py3-none-any.whl (21.0 kB) Copy SHA256 Checksum SHA256 3.4 Wheel Aug 7, 2014
pyxdg-open-0.2.1.tar.gz (29.9 kB) Copy SHA256 Checksum SHA256 Source Aug 7, 2014

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting