---
title: How to migrate from mir-kiosk to Ubuntu Frame
description: Canonical makes open source secure, reliable and easy to use, providing
  support for Ubuntu and a portfolio of enterprise-grade technologies. Founded in
  2004, Canonical operates globally with team members in over 80 countries.
url: https://canonical-com-2950.demos.haus/mir/docs/how-to-migrate-from-mir-kiosk-to-ubuntu-frame?format=md
---

*Submit*

# How to migrate from mir-kiosk to Ubuntu Frame

This document explains how to migrate from the legacy mir-kiosk display server to Ubuntu Frame.

**Contents**

* [Update an existing installation](https://canonical-com-2950.demos.haus/mir/docs/how-to-migrate-from-mir-kiosk-to-ubuntu-frame?format=md#heading--update-an-existing-installation)
* [Use a custom image](https://canonical-com-2950.demos.haus/mir/docs/how-to-migrate-from-mir-kiosk-to-ubuntu-frame?format=md#heading--use-a-custom-image)

---

[Ubuntu Frame](https://mir-server.io/ubuntu-frame/) is the recommended way to enable embedded graphics on Ubuntu Core. It replaces mir-kiosk and provides an improved experience. New features will only be added to Ubuntu Frame, while mir-kiosk will remain maintained until we can decommission it.

Some existing improvements are:

1. Support for an on-screen keyboard
2. A more powerful and easier configuration system
3. A more polished “developer story”
4. `idle-timeout` option for power saving
5. A `ubuntu-frame.screenshot` utility

Ubuntu Frame was announced in October 2021, so it is already a true and proven solution. Your migration from mir-kiosk should be planned as soon as possible. This document aims to help you migrate to the new solution as a drop-in replacement.

## [Update an existing installation](https://canonical-com-2950.demos.haus/mir/docs/how-to-migrate-from-mir-kiosk-to-ubuntu-frame?format=md#heading--update-an-existing-installation)

The simplest way to migrate a device that you have shell access to, is to disable mir-kiosk, install Ubuntu Frame and transfer the configuration over:

```
snap stop mir-kiosk
snap install ubuntu-frame
snap set ubuntu-frame config="$( cat /var/snap/mir-kiosk/current/miral-kiosk.config )"
snap set ubuntu-frame display="$( cat /var/snap/mir-kiosk/current/miral-kiosk.display )"
snap set ubuntu-frame daemon="$( snap get mir-kiosk daemon )"
snap disable mir-kiosk
# or, to remove it completely
snap remove --purge mir-kiosk
```

Your device should now be running Ubuntu Frame configured identically to mir-kiosk.

You will also need to connect your application to the `ubuntu-frame` snap and potentially restart it:

```
snap connect <your-application>:wayland ubuntu-frame
snap restart <your-application>
```

Below is a handy script that you can run on your target, optionally passing your application name as argument. If anything goes wrong, it will try and bring back mir-kiosk.

```
#!/bin/bash

set -ex

! snap list mir-kiosk && echo "No current mir-kiosk installation found!" && exit 1

APP=$1
! snap list ${APP} && echo "${APP} snap not found!" && exit 2

_exit() {
  if [ $? -ne 0 ]; then
    set +e
    snap disable ubuntu-frame
    snap enable mir-kiosk
    snap restart mir-kiosk
    if [ -n "${APP}" ]; then
      snap connect ${APP}:wayland mir-kiosk
      snap restart ${APP}
    fi
  fi
}

trap _exit EXIT

snap stop mir-kiosk
snap install ubuntu-frame
snap set ubuntu-frame config="$( cat /var/snap/mir-kiosk/current/miral-kiosk.config )"
snap set ubuntu-frame display="$( cat /var/snap/mir-kiosk/current/miral-kiosk.display )"
snap set ubuntu-frame daemon="$( snap get mir-kiosk daemon )"
snap disable mir-kiosk

if [ -n "${APP}" ]; then
  snap connect ${APP}:wayland ubuntu-frame
  snap restart ${APP}
fi
```

## [Use a custom image](https://canonical-com-2950.demos.haus/mir/docs/how-to-migrate-from-mir-kiosk-to-ubuntu-frame?format=md#heading--using-a-custom-image)

If you used a custom model and image, you just need to replace mir-kiosk with ubuntu-frame in your model assertion and provide your configuration options in the new format. An example config looked like follows:

```
defaults:
  rW4inp7UbJb1YBxWr6SVebxa3Yv7K1Vm:  # snap-id for mir-kiosk
    cursor: software
    daemon: true
    display-layout: default
    vt: 4
    display-config: |
      layouts:
        default:
          cards:
          - card-id: 0
            HDMI-A-1:
              # ...
```

You will need to convert it to look like so:

```
defaults:
  BPZbvWzvoMTrpec4goCXlckLe2IhfthK:  # snap-id for ubuntu-frame
    daemon: true
    config: |
      cursor=software
      display-layout=default
      vt=4
    display: |
      layouts:
        default:
          cards:
          - card-id: 0
            HDMI-A-1:
              # ...
```

A big benefit of Ubuntu Frame over mir-kiosk is that under the `config` key you can provide any of the [supported Ubuntu Frame options](https://canonical-com-2950.demos.haus/mir/docs/ubuntu-frame-configuration-options), which previously required a much more complex approach with preparation scripts. You can now build the new image / model and deploy it to the device or proceed with a remodel.

---

[Previous

How-to guides](https://canonical-com-2950.demos.haus/mir/docs/how-to-guides)
[Next

Maintaining Discourse documentation](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation)

Last updated 4 years ago. [Help improve this document in the forum](https://discourse.ubuntu.com/t/how-to-migrate-from-mir-kiosk-to-ubuntu-frame/27204).