Ubuntu Frame OSK Documentation

This document describes how to work with the Ubuntu Frame OSK


Ubuntu Frame OSK is the easiest way to add on-screen keyboard support to Ubuntu Frame. To create Ubuntu Frame OSK, we selected Squeekboard, an on-screen keyboard built by Purism for the Librem 5. We chose Squeekboard because it’s modern, stable, and actively maintained. Maintainers and contributors also made Squeekboard really easy to work with, plus it supports a large and growing number of languages and layouts, such as US, German, Russian, Arabic, and many more.

Setup System

Make sure you’ve installed and refreshed Ubuntu Frame.

For the on-screen keyboard to work, you’ll need to use it with an app that supports a text input Wayland protocol (zwp_text_input_v3 or zwp_text_input_v2). Some apps and toolkits known to work are: Firefox, wpe-webkit-mir-kiosk, GTK, Flutter and Qt. Legacy X11 apps do not work with the OSK.

Install Ubuntu Frame OSK

To install the snap, run:

sudo snap install ubuntu-frame-osk

If on a classic system, make sure it’s connected to the Wayland interface:

snap connect ubuntu-frame-osk:wayland

On Ubuntu Core, Ubuntu Frame OSK runs automatically on startup. By default it does not do this on classic systems. If you want to turn this behavior on or off:

sudo snap set ubuntu-frame-osk daemon=true
sudo snap set ubuntu-frame-osk daemon=false

You can also manually run Ubuntu Frame:


Once Ubuntu Frame, an OSK-supporting app and Ubuntu Frame OSK are all running on the same Wayland display, the OSK should appear whenever you click a text field.



To enable or disable the OSK daemon (which makes it run automatically on startup):

sudo snap set ubuntu-frame-osk daemon=true
sudo snap set ubuntu-frame-osk daemon=false


You can switch between light and dark mode with the theme option:
sudo snap set ubuntu-frame-osk theme=dark
sudo snap set ubuntu-frame-osk theme=light


To list all available languages/keyboard layouts:


To change the layout, set the layout option to the desired ID. For example, to use Arabic:

sudo snap set ubuntu-frame-osk layout=ara

You can enable multiple layouts. For example, to set layouts used in Switzerland:

sudo snap set ubuntu-frame-osk layout=ch,ch+fr,us

The first is used by default, and the other’s are available in the menu opened by the layout button in the bottom left. The emoji and terminal layouts are always available.

Modifying the layout

If the existing layout does not work for you, you can provide a custom one. It needs to be placed in $SNAP_USER_DATA/.local/share/squeekboard/keyboards, following the file/folder layout from Squeekboard upstream.

See this for upstream documentation on layouts:


NB: this may break with updates to ubuntu-frame-osk, so tread carefully.

Here’s an example how you can modify the number layout:

$ sudo snap run --shell ubuntu-frame-osk.list-layouts \
   -c 'mkdir --parents --verbose $SNAP_USER_DATA/.local/share/squeekboard/keyboards/number'
mkdir: created directory '/root/snap/ubuntu-frame-osk/302/.local'
mkdir: created directory '/root/snap/ubuntu-frame-osk/302/.local/share'
mkdir: created directory '/root/snap/ubuntu-frame-osk/302/.local/share/squeekboard'
mkdir: created directory '/root/snap/ubuntu-frame-osk/302/.local/share/squeekboard/keyboards'
mkdir: created directory '/root/snap/ubuntu-frame-osk/302/.local/share/squeekboard/keyboards/number'

$ curl --silent https://gitlab.gnome.org/World/Phosh/squeekboard/-/raw/v1.17.1/data/keyboards/number/us.yaml \
  | sudo snap run --shell ubuntu-frame-osk.list-layouts \
      -c 'cat > $SNAP_USER_DATA/.local/share/squeekboard/keyboards/number/us.yaml'

$ sudo editor $( \
    sudo snap run --shell ubuntu-frame-osk.list-layouts \
      -c 'echo $SNAP_USER_DATA/.local/share/squeekboard/keyboards/number/us.yaml' )

Modify the layout to your liking and restart the OSK:

sudo snap restart ubuntu-frame-osk
1 Like

Hi @sophie-w,

I believe the following config must be added to get it working:

snap set ubuntu-frame config "

Hi @viniciusoliveira,

Hi, that shouldn’t be necessary and I need a bit more information to work out what’s happening.

  1. What operating system are you using?
  2. How are you running Ubuntu Frame and Ubuntu Frame OSK? From the command line? As daemons?


This probably duplicates the discussion at


1 Like

Is it possible to hide the keyboard if no input has focus?

That’s how it works.

1 Like

A post was split to a new topic: Ubuntu Frame OSK not showing up

This doesn’t work for me. I’ve installed ubuntu-frame and ubuntu-frame osk on Ubuntu Core 22, and I’ve set the URL for wpe-webkit-mir-kiosk to my local AdGuard Home URL. I’ve logged in using the on-screen keyboard, but after logging in the OSK stays on top of the dashboard page although there’s no input widget anymore on that page. Even navigating to other pages doesn’t hide the OSK.

I’ve installed wpe-webkit-mir-kiosk, ubuntu-frame and ubuntu-frame-osk and set the url to https://www.google.co.uk/.

If I click on the search entry, the keyboard appears, if I click elsewhere it disappears.

I can’t know what your local website is doing, but I would guess it is indicating to the browser that it is expecting text input.

1 Like

Ok, then it’s a bug in AdGuard Home, I’ll investigate and report there. Thanks!


Is there a hide keyboard option. This is needed as I am having keyboard focus issues where clicking outside the keyboard area does not hide the keyboard.

Thank you!

1 Like

@gips0131 no, that is not currently a feature of Squeekboard. So far as I see, it has not been raised as a feature request there, so it is unlikely to happen.

The keyboard appears when requested by the application (you don’t say which application you are using). That should only be when focus is on a text input field: If the application is not doing that, the problem is with the application.

1 Like

Hi @alan_g,

If I am understanding correctly, the keyboard should disappear when clicking outside of a text input field? If so, how can I correct the application to work with the keyboard?

Thank you!

That is a problem for the developer of the app or of the toolkit the app is built with

1 Like

Is it possible to set the behavior of osk when using it with wpe-webkit-mir-kiosk to float over the webpage instead of re-sizing it?

Hi @finelytuned — not at the moment, no. You’d have a problem reaching the bottom of the page in such a case (which could very well be where your input field is).

It would require WPE and the OSK communicate to agree that a) WPE can react to the OSK overlaying it and b) the OSK letting WPE know that’s happening, and its geometry.

We’d love that for the future, but until then we’ve gone for the safer option of resizing the app surface.

Ubuntu Core 22 with ubuntu-frame installed, after installing the ubuntu-frame-osk, the OSK is not working when having input boxes.
When checking the logs of ubuntu-frame-osk, I can see errors:

2023-05-22T08:07:58Z systemd[1]: Started Service for snap application ubuntu-frame-osk.daemon.
2023-05-22T08:07:58Z ubuntu-frame-osk.daemon[106482]: cat: /var/snap/ubuntu-frame-osk/265/osk-gtk-theme.txt: No such file or directory
2023-05-22T08:07:58Z systemd[1]: snap.ubuntu-frame-osk.daemon.service: Main process exited, code=exited, status=1/FAILURE
2023-05-22T08:07:58Z systemd[1]: snap.ubuntu-frame-osk.daemon.service: Failed with result 'exit-code'.
2023-05-22T08:08:01Z systemd[1]: snap.ubuntu-frame-osk.daemon.service: Scheduled restart job, restart counter is at 1.
2023-05-22T08:08:01Z systemd[1]: Stopped Service for snap application ubuntu-frame-osk.daemon.
2023-05-22T08:08:01Z systemd[1]: Started Service for snap application ubuntu-frame-osk.daemon.
2023-05-22T08:08:02Z ubuntu-frame-osk.daemon[106551]: Setting input sources to [('xkb', 'us')]
2023-05-22T08:08:02Z ubuntu-frame-osk.daemon[106551]: Debug: Tried file "/root/snap/ubuntu-frame-osk/265/.local/share/squeekboard/keyboards/us.yaml", but it's missing: No such file or directory (os error 2)
2023-05-22T08:08:02Z ubuntu-frame-osk.daemon[106551]: Info: Loaded layout Resource: us
2023-05-22T08:08:02Z ubuntu-frame-osk.daemon[106551]: Debug: Tried file "/root/snap/ubuntu-frame-osk/265/.local/share/squeekboard/keyboards/us.yaml", but it's missing: No such file or directory (os error 2)
2023-05-22T08:08:02Z ubuntu-frame-osk.daemon[106551]: Info: Loaded layout Resource: us
2023-05-22T08:08:02Z -[106551]: Could not connect to session manager: Cannot autolaunch D-Bus without X11 $DISPLAY

2023-05-22T08:08:02Z -[106551]: Failed to init libfeedback: Cannot autolaunch D-Bus without X11 $DISPLAY

What is the actual issue here?

I noticed when the content_purpose is set to number, e.g. HTML: <input type="number">, a special number mode pops up in OSK to only allow number entry. This number mode doesn’t seem to support the decimal separator, and there is no way to switch to another keyboard.

Does anyone have a solution for this?

Hi @hashbrown6099, sorry for the late reply. Reading e.g. the Mozilla docs on number input, you need to set step to the lowest increment you want to allow.

Regardless, it looks like the upstream number layout does not include the decimal point:


However, you can override that layout by placing a copy of it, with the changes you want, in $SNAP_USER_COMMON, and that will take precedence.

I’ll update the above post to include a guide on how to do it.

EDIT: Done:

1 Like

Hi @christof-ameye-osc, sorry - your message missed our radar.

What is your client application? The logs you provided look quite normal.

Hi. Is it possible to disable Emoji and terminal key layouts?
And when using us.yaml and when us_wide.yaml file?