1.17. Soft Keyboard

Oracle VM VirtualBox provides a soft keyboard that enables you to input keyboard characters on the guest. A soft keyboard is an on-screen keyboard that can be used as an alternative to a physical keyboard. See Section 1.17.1, “Using the Soft Keyboard” for details of how to use the soft keyboard.


For best results, ensure that the keyboard layout configured on the guest OS matches the keyboard layout used by the soft keyboard. Oracle VM VirtualBox does not do this automatically.

Figure 1.15 Soft Keyboard in a Guest Virtual Machine

The soft keyboard can be used in the following scenarios:

  • When the physical keyboard on the host is not the same as the keyboard layout configured on the guest. For example, if the guest is configured to use an international keyboard, but the host keyboard is US English.

  • To send special key combinations to the guest. Note that some common key combinations are also available in the Input, Keyboard menu of the guest VM window. See Section 1.8.3, “Typing Special Characters”.

  • For guests in kiosk mode, where a physical keyboard is not present.

  • When using nested virtualization, the soft keyboard provides a method of sending key presses to a guest.

By default, the soft keyboard includes some common international keyboard layouts. You can copy and modify these to meet your own requirements. See Section 1.17.2, “Creating a Custom Keyboard Layout”.

1.17.1. Using the Soft Keyboard

  1. Display the soft keyboard.

    In the guest VM window, select Input, Keyboard, Soft Keyboard.

  2. Select the required keyboard layout.

    The name of the current keyboard layout is displayed in the task bar of the soft keyboard window. This is the previous keyboard layout that was used.

    Click the Layout List icon in the task bar of the soft keyboard window. The Layout List window is displayed.

    Select the required keyboard layout from the entries in the Layout List window.

    The keyboard display graphic is updated to show the available input keys.

  3. Use the soft keyboard to enter keyboard characters on the guest.

    • Modifier keys such as Shift, Ctrl, and Alt are available on the soft keyboard. Click once to select the modifier key, click twice to lock the modifier key.

      The Reset the Keyboard and Release All Keys icon can be used to release all pressed modifier keys, both on the host and the guest.

    • To change the look of the soft keyboard, click the Settings icon in the task bar. You can change colors used in the keyboard graphic, and can hide or show sections of the keyboard, such as the NumPad keys.

1.17.2. Creating a Custom Keyboard Layout

You can use one of the supplied default keyboard layouts as the starting point to create a custom keyboard layout.


To permananently save a custom keyboard layout, you must save it to file. Otherwise, any changes you make are discarded when you close down the Soft Keyboard window.

Custom keyboard layouts that you save are stored as an XML file on the host, in the keyboardLayouts folder in the global configuration data directory. For example, in $HOME/.config/VirtualBox/keyboardLayouts on a Linux host.

  1. Display the Layout List.

    Click the Layout List icon in the task bar of the soft keyboard window.

  2. Make a copy of an existing keyboard layout.

    Highlight the required layout and click the Copy the Selected Layout icon.

    A new layout entry with a name suffix of -Copy is created.

  3. Edit the new keyboard layout.

    Highlight the new layout in the Layout List and click the Edit the Selected Layout icon.

    Enter a new name for the layout.

    Edit keys in the new layout. Click on the key that you want to edit and enter new key captions in the Captions fields.

    The keyboard graphic is updated with the new captions.

  4. (Optional) Save the layout to file. This means that your custom keyboard layout will be available for future use.

    Highlight the new layout in the Layout List and click the Save the Selected Layout into File icon.

    Any custom layouts that you create can later be removed from the Layout List, by highlighting and clicking the Delete the Selected Layout icon.