Matchbox Keyboard Raspberry Pi

Virtual Keyboard for the Raspberry Pi

Matchbox-keyboard is an on screen ‘virtual’ or ‘software’ keyboard which works well for small touchscreen TFTs connected to a Raspberry Pi.

Matchbox-keyboard also uses XML files to specify the layout of the keys, which makes it highly customizable.

The touchscreen used in the above video is a PiScreen.

1. Install prerequisite development files

pi@raspberrypi ~ $ sudo apt-get install libfakekey-dev libpng-dev libxft-dev autoconf libtool -y

2. Install and compile matchbox-keyboard

pi@raspberrypi ~ $ git clone
pi@raspberrypi ~ $ cd matchbox-keyboard
pi@raspberrypi ~ $ ./
pi@raspberrypi ~ $ make
pi@raspberrypi ~ $ sudo make install

Installation of the shared matchbox libraries needs to be done after the installation of matchbox-keyboard.

pi@raspberrypi ~ $ sudo apt-get install libmatchbox1 -y

3. Create toggle script to start or stop matchbox-keyboard
We will now create a script to toggle the keyboard on and off. And then add a menu item to access the script as well as add an icon to the task bar for easy access.


Create a new file;

pi@raspberrypi ~ $ sudo nano /usr/bin/

And copy in the text below;

#This script toggle the virtual keyboard

PID=`pidof matchbox-keyboard`
if [ ! -e $PID ]; then
  killall matchbox-keyboard

Now make it executable;

pi@raspberrypi ~ $ sudo chmod +x /usr/bin/

We will now add an item to the start menu.

pi@raspberrypi ~ $ sudo nano /usr/local/share/applications/toggle-matchbox-keyboard.desktop

Copy in this text;

[Desktop Entry]
Name=Toggle Matchbox Keyboard
Comment=Toggle Matchbox Keyboard

To create an icon on the task bar, open up the LXDE panel config;

pi@raspberrypi ~ $ nano ~/.config/lxpanel/LXDE/panels/panel


PiScreen TFT Raspberry Pi


Find this section of config (it is near the bottom);

Plugin {
    type = launchbar
    Config {
        Button {
        Button {

and change it to;

Plugin {
    type = launchbar
    Config {
        Button {
        Button {
        Button {

More Information

Matchbox-keyboard can be started from the command line with the below statement. This needs to be run from a command prompt within X which is running on the touch screen;

pi@raspberrypi ~ $ matchbox-keyboard

Alternately, if you have SSH’d in from another PC, use;

pi@raspberrypi ~ $ DISPLAY=:0.0 matchbox-keyboard

This will load the default keyboard layout, seen here;

Matchbox-keyboard can also resize the window with the -s integer argument. Integer is a value between 30%-100% of the screen width.
Here is the defualt keyboard layout loaded at 50% of screen width;

pi@raspberrypi ~ $ matchbox-keyboard -s 50


Matchbox-keyboard also supports custom keyboards, and there are a few loaded with the install into /usr/local/share/matchbox-keyboard/. It is very easy to build your own.

pi@raspberrypi ~ $ matchbox-keyboard -s 50 extended


29 thoughts on “Virtual Keyboard for the Raspberry Pi”

  1. Pingback: <CONTENT /> v.6
  2. Remember to install libxft-dev if not done befor (sudo apt-get -y install libxft-dev).
    Otherwise the error:
    configure: error: *** Required Xft Library not found ***
    will occur.

      1. DISPLAY=:0.0 matchbox-keyboard
        matchbox-keyboard: error while loading shared libraries: cannot open shared object file: No such file or directory

        i see nothing

  3. I’m using Rasbian Jessie with Kernel 3.12.26 and I can’t install matchbox-keyboard. I used the following commands:
    git clone
    cd matchbox-keyboard

    the results: > base-fragment-et_EE.xml.tmp
    cp base-fragment-et_EE.xml.tmp base-fragment-et_EE.xml
    make[2]: *** No rule to make target ‘’, needed by ‘keyboard-extended.xml.tmp’. Schluss.
    rm base-fragment-da_DK.xml.tmp base-fragment-et_EE.xml.tmp
    make[2]: Leaving directory ‘/home/pi/matchbox-keyboard/layouts’
    Makefile:486: recipe for target ‘all-recursive’ failed
    make[1]: *** [all-recursive] Error 1
    make[1]: Leaving directory ‘/home/pi/matchbox-keyboard’
    Makefile:375: recipe for target ‘all’ failed
    make: *** [all] Error 2

    1. in ~/matchbox-keyboard/layouts/, “” file is missing.

      cd ~/matchbox-keyboard/layouts/
      cp keyboard-extended.xml

      then retry.

  4. First of all thanks for the awesome PiScreen. I am a beginner with Raspberry Pi. I was wondering if it is possible to support multiple PiScreens simultaneously with a single Raspberry Pi or Banana Pi or any of its high-end variants? Can I connect PiScreen using USB port and what can I do to achieve this?

    I shall be grateful for the response and any helpful details/insights into this.



    1. first try loading the extended keyboard and see if that gives you what you want
      matchbox-keyboard extended

      Otherwise, read the README in the source directory. It has a section titled “Making your own keyboard layouts”

  5. I could not get the toggle script to work properly until I changed the line:
    PID=’pidof matchbox-keyboard’
    To this:
    PID=$(pidof matchbox-keyboard)

    It would only keep launching additional keyboards before making this change.

    I can’t tell you exactly why… I just kept looking at examples of scripts and looking for other ways to write it until I got it to work.

  6. Hello,

    I have change

    matchbox-keyboard -s 75 extended&


    sudo nano /usr/bin/

    But, when i launch the matchbox on the menu, it alway launch the “Standart” non extended keyboard. what’s wrong?

    Alors after changer text in ~/.config/lxpanel/LXDE/panels/panel and rebboted the device, the line i have editer have diseapear, now , POWER and LOCK icon has diseaper from the taskbar, i dont know why

    1. Hello,

      It’s now working, i have erase all space or “tab” space and now it’s working (on your example, have space and Tab and i have delete it and woking great now)

      I have just a question, it is possible to have a “more extended” keyboard (like with Up,Down,Right,Left, inser, home, delete, etc… Key)?

      Best regards.


  7. I have followed the installation instructions and the standard matchbox keyboard works fine. When I try to get the extended version to work:

    matchbox-keyboard extended

    I get “Segmentation fault”. Can you help me troubleshoot this?

  8. This edit location has changed for the Pi2
    pi@raspberrypi ~ $ nano ~/.config/lxpanel/LXDE/panels/panel
    it is now
    pi@raspberrypi ~ $ nano ~/.config/lxpanel/LXDE-pi/panels/panel
    Will this affect any of the coding?
    It seems to work.

Leave a Reply