To install PyWayland, you will need to have a base set of dependencies installed. This should be all the configuration that is required to run the packaged version on PyPI. The additional steps to build and install from source are outlined below.

If you have any problems with anything outlined here, feedback is greatly appreciated.

External Dependencies

In order to run PyWayland, you will need to have installed the Wayland libraries and headers such that they can be found by CFFI. This can be done with the libwayland-dev apt package; however, note that it is probably best to use the most recent version of Wayland available from the Wayland releases site, and the pip package will try to track the most recent version.

You will also need to have the Python headers installed and a version of GCC to compile the cffi library. The headers are typically available through the python-dev package.

Optionally, you can have installed the wayland-protocols package, also available from the Wayland releases page. The package uploaded to PyPI will already have these protocols included, so this is only needed if you plan on installing from source.

Installing with pip

Once the external dependencies are in place you should just be able to run:

$ pip install pywayland

Any additional unfulfilled dependencies should be downloaded.

Installing from Source

You can download and run PyWayland from source, which will not only give you the latest improvements and fixes, but will let you build the protocol files against a different version than is available through pip (the version of Wayland the protocol is compiled against is listed on the top of the PyPI page).

Getting the Source

You can download the most recent version of PyWayland from the git repository, or clone the repository as:

$ git clone

Python Dependencies

PyWayland depends on a minimal set of dependencies. All Python version require cffi (to perform Wayland library calls), which can be pip installed for non-PyPy installations. Note that PyPy platforms ship with cffi.

Generating the Wayland Protocol

At this point, you have the base PyWayland module, which contains some core objects and objects specific to client and server implementations. The client and server exchange messages defined in the Wayland protocol, which is an XML file that ships with Wayland. The scanner parses this XML file and generates the relevant objects.

If the Wayland protocol file is in the default location (/usr/share/wayland/wayland.xml) or can be found with pkg-config, you should be able to build the protocol files without any problems:

$ python -m pywayland.scanner

This will output the protocol files to the directory ./pywayland/protocol/. The input file and the output directory can be set from the command line options, see python -m pywayland.scanner -h for more information.

Running PyWayland inplace

Once the protocol files are created, you can generate the cffi module. Note: this is only required if you want to run from the source in place. If the libwayland header files are correctly installed, you will just need to run:

$ python pywaland/

At this point, you should be able to use the PyWayland library. You can check that you have everything installed correctly by running the associated test-suite (note that you will also need pytest to run the tests). Simply run:

$ pytest

from the root directory.

Installing PyWayland

The package can be installed from source using typical mechanisms:

$ python install

Additional arguments can be used to automatically generate the Wayland protocols for the standard Wayland package (which will fail if it cannot run) and the wayland-protocols package (which will be attempted by default, but will not raise an error if it fails).

If you have any problems or have any feedback, please report back to the issue tracker, contribution is always welcome, see Contributing.