Setting up an On-Screen Keyboard on the Raspberry Pi

This guide will show you how to set up an on-screen keyboard for your Raspberry Pi.

Raspberry Pi On-Screen Keyboard

An on-screen keyboard can be incredibly useful for your Raspberry Pi in a variety of different cases.

For example, if you are using your Raspberry Pi with a touchscreen display, using an on-screen keyboard is one of the best ways of adding keyboard input.

Additionally, if you are running a Pi that does not have a keyboard connected and only a mouse, then using an on-screen keyboard will allow you to type still.

Installing an on-screen keyboard to your Raspberry Pi is a straightforward and quick task.

We will also be showing you how to add an icon to the taskbar to quickly toggle the virtual keyboard on and off.

Equipment List

Here is a list of the equipment we recommend for this guide on setting up an on-screen keyboard on your Raspberry Pi.


Raspberry Pi 1, 2, 3 or 4

Micro SD Card

Power Supply

Ethernet Cord or WiFi dongle (The Pi 3 and 4 has WiFi inbuilt)


Raspberry Pi Case

This guide was tested on a Raspberry Pi 4 running Raspbian Buster. This guide should work successfully on older versions of Raspbian as well.

Installing the On-Screen Keyboard Software to your Raspberry Pi

1. Before we can install the on-screen keyboard, we must first update our Raspberry Pi.

To upgrade the packages, we need to run the following two commands.

sudo apt update
sudo apt upgrade

Depending on how long it has been since you last updated, this process can take some time, so be patient.

2. Now that we have updated our Raspberry Pi, we can go ahead and install the software we want.

To install the virtual keyboard software, all we need to do is run the following command.

sudo apt install matchbox-keyboard

We chose to use the matchbox-keyboard package as its the most stable for the Raspberry Pi while also not chewing up to much of the Pi’s limited resources.

Opening the Virtual Keyboard on the Raspberry Pi

In this section, we will be showing you how to open the on-screen keyboard using both the terminal and the desktop menu.

Using the Desktop to Open the On-Screen Keyboard

1. Once you are on the desktop of your Raspberry Pi, click the icon in the top-left hand corner of the screen.

Open Start Menu - Raspberry Pi Icon

This icon will bring up the start menu for the operating system.

2. Next, hover over “Accessories” (1.), this will bring up an additional menu

Within this new menu, clickKeyboard” (2.) to launch the software.

Raspberry Pi Open Virtual Keyboard App

3. The virtual keyboard should now be displayed on your Raspberry Pi’s desktop.

You can click/tap the letters to type into any textbox.

On Screen Keyboard Software Running

Using the Terminal to Launch the Virtual Keyboard

If you can’t find the keyboard option within the start menu, you can also use the terminal to launch the software.

It is also possible to complete this section using SSH if you have no keyboard to connect to the Pi itself.

1. Start by opening up a terminal session on your Raspberry Pi whether that be over SSH or on the Pi itself.

2. Now within this terminal session, run one of the following commands.

The command you need to use differs if you are using SSH or running it directly on your Pi.

The reason for this is that we need to specify the display we want the virtual keyboard to display on when using SSH.

On the Raspberry Pi


Over SSH

DISPLAY=:0 matchbox-keyboard &

This command will load up the on-screen keyboard software on your Raspberry Pi.

Adding a Virtual Keyboard Toggle to the Taskbar

This section of the guide will show you how you can modify Raspbian so that you can add a keyboard toggle to your taskbar.

We will be making it so that when you click this button, it will automatically open and close the on-screen keyboard software.

1. We will start by creating the bash script that will toggle the matchbox software.

Begin writing this script in the “/usr/bin/” folder by running the following command.

sudo nano /usr/bin/

2. Within this file, enter the following lines of code.

PID="$(pidof matchbox-keyboard)"
if [  "$PID" != ""  ]; then
  kill $PID
 matchbox-keyboard &

This script is relatively straightforward. It first tries to grab the id of the virtual keyboard software and stores it in a bash variable called PID.

If it gets a process id, then the script will kill the currently running on-screen keyboard.

Otherwise, if there was no process id for the software, it will start it up by running the matchbox-keyboard command.

3. Once done, please save the file by pressing CTRL + X, then Y, followed by ENTER.

4. With our script created, we need to give everyone the execute privileges so that they can run it.

You can read more about permissions in linux with our file permissions in Linux guide.

To add the execute permission, run the following command.

sudo chmod +x /usr/bin/

If you would like to learn more about this command, check out our basics of chmod guide.

5. Next, we need to create the file which the taskbar will read to load our toggle button.

Begin creating this file by using the command below.

sudo nano /usr/share/raspi-ui-overrides/applications/toggle-keyboard.desktop

6. Within this file, enter the following lines.

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

This text tells the operating system how it should display the entry, as well as telling it should execute the script we wrote when clicked.

7. Now, please save the file by pressing CTRL + X, then Y, followed by ENTER.

8. Next, we need to copy over the default configuration file over to our pi users config folder.

We will be modifying this file to add our on-screen keyboard button.

cp /etc/xdg/lxpanel/LXDE-pi/panels/panel /home/pi/.config/lxpanel/LXDE-pi/panels/panel

9. Finally, we need to modify the configuration for the pi user so that the icon is added to the taskbar.

Run the command below to begin modifying the panel configuration.

nano /home/pi/.config/lxpanel/LXDE-pi/panels/panel

10. To the bottom of this file, add the following text.

Plugin {
  Config {
    Button {

This bit of text creates an entry in the taskbar. It tells the taskbar to utilize the toggle-keyboard.desktop file we created earlier on in this section to display our toggle button.

11. Once added, please save the file by pressing CTRL + X, then Y, followed by ENTER.

12. To show our new button in the taskbar, we need to restart our Raspberry Pi by running the following command.

sudo reboot

13. When your Raspberry Pi finishes rebooting, you should now see the keyboard icon in the top right-hand corner of the screen.

By clicking this icon, you can toggle the on-screen keyboard on your Raspberry Pi on and off.

Raspbian Keyboard Taskbar Button

Hopefully, at this stage, you have now successfully set up an on-screen keyboard on your Raspberry Pi.

If you have had any trouble with the virtual keyboard software, feel free to drop a comment below.


  1. Avatar for tutness
    tutness on

    YEAY! thank you so much 🙂
    I now have an on screen-keyboard, with a handy-dandy icon toggle 😀

  2. Avatar for Brendan
    Brendan on

    just set this up working. thanks heeps

  3. Avatar for Dayne
    Dayne on


    I can navigate to and see the lxpanel directory but when I try to run “cp /etc/xdg/lxpanel/LXDE-pi/panels/panel /home/pi/.config/lxpanel/LXDE-pi/panels/panel” the system tells me there is no such file or directory. (btw I used cd to find our which directory it was getting hung up on). Any ideas?

    Thanks for your time and I hope you have a great day!

    1. Avatar for Emmet
      Emmet on

      Hi Dayne,

      May I ask what operating system you are currently using and the version?

      Additionally, what ever folders are available from within the lxpanel directory.

      I quickly tested this on a fresh installation of Raspberry Pi OS Buster and everything worked as intended.


  4. Avatar for Stevie W
    Stevie W on

    Working well both for my 3B+ with a touch screen display, and 4B with an HDMI display.

    Thank you so much for the clear instructions.

  5. Avatar for Zod
    Zod on

    Worked well for me. Raspberry PI 4 OS release 10

  6. Avatar for Bob Med
    Bob Med on

    Hi Emmet, thanks for these very good and detailled instructions. For me getting the button in the desktop worked only when adding the configuration at the end of the file, not at the beginning.

  7. Avatar for Justin
    Justin on

    Keyboard does not terminate when clicking on icon. A new duplicate keyboard starts

    I get [: pidof: binary operator expected

    kill code below

    PID=’pidof matchbox-keyboard’
    If [ ! -e $PID]; then kill $PID

    What is “-e”?

    1. Avatar for Emmet
      Emmet on

      Hi Justin,

      I have gone ahead and updated the script to be slightly different.

      It should behave the same but be less prone to typing errors. it looks like you used the apostrophe instead of the backtick around pidof matchbox-keyboard.

      The -e argument is actually used to check if a file exists. So the original code while it worked was technically incorrect.

      Please try the updated version in the tutorial to see if it works.


  8. Avatar for HollowSavant
    HollowSavant on

    This is like needing scissors to open up your brand new scissor’s package….. wish this was part of the base OS.

    1. Avatar for Emmet
      Emmet on

      Hi Hollow,

      I agree that this should be in some way implemented in to base Raspberry Pi OS.

      It definitely makes the first experience of using a touch based screen with a Raspberry Pi a bit of a tedious process.


  9. Avatar for Bogdan
    Bogdan on

    I will never understand why the on-screen keyboard is not included by default in the Raspbian packages.
    My pi’s are all running without any keyboard attached to them, so having an on screen keyboard is essential especially if you have network connection problems.

  10. Avatar for Christian Becker
    Christian Becker on

    Thanks, that was very useful.
    Up until now I just started the matchbox-keyboard using the start menu. The toggle is so much better.

  11. Avatar for Brian
    Brian on

    Raspberry pi 4 2GB Running Buster

    Keyboard icon doesn’t show for me either. I have used File Manager to check and all the new files are where they should be, and those that should be executable are indeed.

    Any pointers would be appreciated.

    1. Avatar for Emmet
      Emmet on

      Hi Brian,

      Did you test the steps I posted below in reply to Angelo?


    2. Avatar for Brian
      Brian on

      Thank you, this is now working fine. For the benefit of anyone else reading this post the thing to watch for is the response to:
      nano /home/pi/.config/lxpanel/LXDE-pi/panels/panel

      If nano reports that ‘panel’ is a new file (as it did originally for me) then this means that ‘panel’ must first be copied (using cp) from:

      I believe it always helps to understand why things work, but for those who don’t care then following your solution blind is the answer.

      Thanks again

    3. Avatar for Brian
      Brian on

      All now working fine. Many thanks for your help.

  12. Avatar for Angelo
    Angelo on

    thanks for your guide, unfortunately the button doesn’t work also for me.
    I have a new installation of Raspbian Buster (desktop version), but I don’t have this path /home/pi/.config/lxpanel/LXDE-pi/panels/panel , but I suppose this /home/pi/.config/pcmanfm/LXDE-pi/desktop-items-0.conf , but if I add your plugin lines, I don’t get the button.
    The keyboard and the bash file work correctly

    1. Avatar for Emmet
      Emmet on

      Hi Angelo,

      Out of interest could you try running the following command

      cp /etc/xdg/lxpanel/LXDE-pi/panels/panel /home/pi/.config/lxpanel/LXDE-pi/panels/panel

      Then modify the file again and try adding the configuration to the bottom again.

      nano /home/pi/.config/lxpanel/LXDE-pi/panels/panel

      Then again restarting the Raspberry Pi.

      sudo reboot


    2. Avatar for Angelo
      Angelo on

      now work correctly, I have the keyboard button! 🙂

  13. Avatar for Martin
    Martin on

    Hi that’s a cool guide
    Open the Keyboard manually worked fine.

    But toggel button on toolbar don’ work:
    I use a raspi 4 and raspian on it, but i didn’t have tha path
    sudo nano /usr/share/raspi-ui-overrides/applications/toggle-keyboard.desktop

    .desktop files are stored instead under /usr/share/applications
    But after all reboot and stuff it doesn’t work with the Toggle Ikon in the Toolbar

    1. Avatar for Emmet
      Emmet on

      Hi Martin,

      I tested this tutorial again and everything is still working as intended.

      May I ask what version of Raspbian you are running? I tested this running a clean copy of the latest version of Raspbian Buster.


  14. Avatar for David
    David on

    Hi Emmet,

    Thanks for putting this out there. It works for me.

    Just one little correction, You typo’d the word MECHANISM.

    1. Avatar for Gus
      Gus on

      Thank you for pointing that out! We have fixed the typo now.

Leave a Reply

Your email address will not be published. Required fields are marked *