Setting up an On-Screen Keyboard on the Raspberry Pi

by Emmet

Updated May 28, 2024

If you buy through our links, we may earn an affiliate commission. Learn More.

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

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.

Optional

Raspberry Pi Case ( Amazon )
USB Keyboard ( Amazon )

This guide was tested on a Raspberry Pi 4 running Raspbian Pi OS. 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.

Raspberry Pi 1, 2 and 3

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 it’s the most stable for the Raspberry Pi while also not chewing up too much of the Pi’s limited resources.

You can now move onto the rest of the tutorial.

Raspberry Pi 4 or 5

If you are using a Raspberry Pi 4 or 5, it is likely you will be using the new Wayland display system rather than X11. Unfortunately, matchbox does not work out of box with Wayland, so we will need to install a different package.

sudo apt install wvkbd

Now skip down to the section on launching the wvkbd keyboard from your terminal.

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

This section is only relevant if you installed the match-box keyboard. If you are using wvkbd, you will need to launch it using the terminal.

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

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, click “Keyboard” (2.) to launch the software.

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.

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.

Using the wvkbd keyboard

1. Open the terminal on your Raspberry Pi.

2. Run the following command in your terminal to launch the keyboard.

wvkbd-mobintl

Using the -h flag will allow you to view some of the options that you can use with the command. For example, resizing the font or the size of the keyboard.

wvkbd-mobintl -h

Using the matchbox keyboard

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

matchbox-keyboard

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 Raspberry Pi OS 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.

This section may not currently work on the latest version of the Raspberry Pi OS.

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/toggle-keyboard.sh

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

#!/bin/bash
PID="$(pidof matchbox-keyboard)"
if [  "$PID" != ""  ]; then
  kill $PID
else
 matchbox-keyboard &
fi

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/toggle-keyboard.sh

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
Exec=/usr/bin/toggle-keyboard.sh
Type=Application
Icon=matchbox-keyboard.png
Categories=Panel;Utility;MB
X-MB-INPUT-MECHANISM=True

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 user’s 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 {
  type=launchbar
  Config {
    Button {
      id=toggle-keyboard.desktop
    }
  }
}

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.

Conclusion

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.

31 Comments

Ashton Peitzmeier on May 19, 2022 at 10:54 am

This may be the best tutorial ever to exist THANKYOU!!

Reply
Oystein on April 28, 2022 at 8:34 am

Is it possible to bring up the virtual keyboard just by entering a text field?
I am using a full screen app called DAKboard and have no access to the top bar.
Thanks!

Reply
1. Emmet on April 29, 2022 at 6:46 pm
  
  Editor
  Hi Oystein,
  
  Sadly the on-screen keyboard software we are utilizing in this tutorial isn’t the most versatile piece of software. As far as I am aware it doesn’t have the ability to do this.
  
  There is an alternative that you can use called Florence that is meant to have this functionality. However, from memory, back when I wrote this tutorial the software was unresponsive on older Raspberry Pi’s.
  
  You can install Florence and the required assistive technology module by using the following line.
  
  sudo apt install at-spi2-core florence
  
  Please let me know if this solves the issues you are having. Also thank you for mentioning that software, its pretty neat and I wouldn’t mind trying it out myself.
  
  Cheers,
  Emmet
  
  Reply
Mark H on January 5, 2022 at 1:56 pm

Brilliant, worked like a charm. Thank you so much!

Reply
marc on December 30, 2021 at 2:59 am

Awesome, thank you!
Note: you don’t need to reboot. Logout and back in will work just as well.

Reply
Vlad on December 29, 2021 at 1:48 am

Thank you! This helped me very much! 😁😁😁

Reply
tutness on October 18, 2021 at 6:14 pm

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

Reply
Brendan on September 30, 2021 at 5:54 pm

just set this up working. thanks heeps

Reply
Dayne on August 25, 2021 at 4:43 pm

Hello,

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!

Reply
1. Emmet on August 26, 2021 at 10:02 pm
  
  Editor
  
  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.
  
  Cheers,
  Emmet
  
  Reply
2. Mazzel on September 26, 2022 at 10:35 pm
  
  I had the same problem, caused by choosing a different username than ‘Pi’ during install of my OS. This could be your case maybe?
  
  The second part of the CP command (/home/pi/.config/lxpanel/LXDE-pi/panels/panel) assumes your username is “pi”, just replace this with the correct username.
  
  Just open a xterm box and check what it says: [username]@raspberrypi:~ $
  
  Reply
Stevie W on April 26, 2021 at 10:47 am

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.

Reply
Zod on February 10, 2021 at 5:09 pm

Worked well for me. Raspberry PI 4 OS release 10

Reply
Bob Med on January 27, 2021 at 7:54 am

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.

Reply
Justin on December 27, 2020 at 1:50 am

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”?

Reply
1. Emmet on December 28, 2020 at 4:16 pm
  
  Editor
  
  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.
  
  Cheers,
  Emmet
  
  Reply
HollowSavant on December 25, 2020 at 10:13 am

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

Reply
1. Emmet on December 25, 2020 at 9:04 pm
  
  Editor
  
  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.
  
  Cheers,
  Emmet
  
  Reply
Bogdan on November 5, 2020 at 3:35 am

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.

Reply
Christian Becker on July 26, 2020 at 8:13 pm

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

Reply
Brian on March 17, 2020 at 6:48 am

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.

Reply
1. Emmet on March 17, 2020 at 11:59 am
  
  Editor
  
  Hi Brian,
  
  Did you test the steps I posted below in reply to Angelo?
  
  Cheers,
  Emmet
  
  Reply
2. Brian on March 17, 2020 at 11:49 pm
  
  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:
  /etc/xdg/lxpanel/LXDE-pi/panels/
  
  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
  
  Reply
3. Brian on March 18, 2020 at 10:53 am
  
  All now working fine. Many thanks for your help.
  
  Reply
Angelo on March 15, 2020 at 10:46 pm

Hi,
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
Thanks

Reply
1. Emmet on March 15, 2020 at 11:02 pm
  
  Editor
  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
  
  Cheers,
  Emmet
  
  Reply
2. Angelo on May 9, 2020 at 7:17 pm
  
  Thanks,
  now work correctly, I have the keyboard button! 🙂
  
  Reply
Martin on March 10, 2020 at 8:28 pm

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

Reply
1. Emmet on March 13, 2020 at 9:55 am
  
  Editor
  
  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.
  
  Cheers,
  Emmet
  
  Reply
David on January 27, 2020 at 5:42 am

Hi Emmet,

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

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

Reply
1. Gus on January 27, 2020 at 2:27 pm
  
  Editor
  
  Thank you for pointing that out! We have fixed the typo now.
  
  Reply