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

If the above file is empty, then it is most likely that you have a newer version of Raspbian, especially if you are using a Pi 2. You then would need to edit the panel config at this location;

pi@raspberrypi ~ $ nano ~/.config/lxpanel-pi/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


45 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.

  9. I executed all steps in the tuturial, but same as frans (AUGUST 29, 2014 AT 1:20 AM) I get the following error message:

    matchbox-keyboard: error while loading shared libraries: cannot open shared object file: No such file or directory

    uname -a
    Linux raspberrypi 3.18.9-v7+ #767 SMP PREEMPT Sat Mar 7 21:52:35 GMT 2015 armv7l GNU/Linux

    Can you please advise? Thanks

      1. Hi Fernando, I appreciate your reply. However:

        “libmatchbox1 is already the newest version.”

        Any other advise?


  10. Hi all, first of all Mark I appreciate all the work that has gone in to this. Very useful tool for the pi with the small touchscreen. First of all the tutorial is well written and concise which I appreciate. In the line “X-MB-INPUT-MECHANSIM=True” is it supposed to be MECHANISM or how its typed? I also have run through this two times. The first time I felt that I had missed installing libmatchbox1 in the appropriate sequence so I reimaged and tried the script again installing libmatchbox at an earlier time. I still receive the
    matchbox-keyboard: error while loading shared libraries: cannot open shared object file: No such file or directory
    I am using the raspian pitft image PiTFT28R_raspbian140620_2014_08_25. I’ve checked the error logs and no error seems to be logged.

    Any and all advice is appreciated this tool would cure a number of remote uses I have in mind for this unit. thanks Jim

  11. Hi.
    I’ve installed the keyboard as per instructions but after running it I can’t open File Manager without a reboot and then if I run matchbox-keyboard File Manager will not open.

    Anyone else having this problem? How can I fix it?

    1. Hi,

      I also got the same problem as Matthew Grant, I just installed the virtual keyboard and cannot access the file manager.
      Has anybody found the fix for this?


    2. I had the same pb.
      I have change the toggle script to load the extended keyboard with 50 % size
      I have also set the keyboard to be always on top. (top left corner menu)
      And now it is ok.
      It is strange but I suspect something with the default full size !

  12. Should the keybord disappear when I touch the launchbar’s icon? Because I get a second keyboard…
    Any suggestions?

Leave a Reply