Scope of Application

This article applies to users who need to install and run the OneKey App on Linux systems.

Dependencies and permission policies may vary across different Linux distributions. This article primarily uses Ubuntu / Debian systems as examples and also provides a general method for configuring udev rules.

Preparation Before Installation: Configure udev Rules

In Linux systems, udev rules are used to ensure the system correctly recognizes the OneKey hardware wallet. Whether you use Snap or AppImage, it is recommended to complete this step first.

Download and install the OneKey udev rules:

sudo curl -fsSL https://data.onekey.so/onekey.rules -o /etc/udev/rules.d/99-onekey.rules

If the system does not havecurlyou can run:

sudo apt update 
sudo apt install curl

Reload udev rules:

sudo udevadm control --reload-rules sudo udevadm trigger

Unplug and replug the OneKey hardware wallet, then open the OneKey App again.

Method 1: Install via Snap

Install Snap:
```
sudo apt update 
sudo apt install snapd
```
If you are using another Linux distribution, refer to the official Snap documentation for installationsnapd.
Install OneKey App:
```
sudo snap install onekey-wallet
```
You can also open the Snap Store page to install:https://snapcraft.io/onekey-wallet
Allow OneKey App to access USB devices:
```
sudo snap connect onekey-wallet:raw-usb
```
Open OneKey App and select to connect the hardware wallet.

If the Snap version fails to start

If you encounter an error like:

error while loading shared libraries: libgbm.so.1: cannot open shared object file

This usually indicates that the graphical library dependencies are missing within the current Snap package.

Because Snap uses sandbox isolation, even if installed on the host systemlibgbm1, Snap applications may not be able to read the host's graphics library.

If you encounter this issue, it is recommended to temporarily switch to the AppImage version or wait for OneKey to update the Snap package before using the Snap version.

Method 2: Download and run the AppImage

Go to the OneKey official website to download the Linux AppImage file:https://onekey.so/download
Dependencies required to install AppImage:
Ubuntu / Debian systems can run:
```
sudo apt update sudo apt install libfuse2
```
If your system prompts that it cannot findlibfuse2please install the corresponding packages according to the current distribution's AppImage / FUSE dependency instructions.
Switch to the directory where the AppImage file is located, for example:
```
cd ~/Downloads
```
Grant execute permissions to the AppImage:
```
chmod +x OneKey-Wallet-*.AppImage
```
Run OneKey App:
```
./OneKey-Wallet-*.AppImage
```

What to do if Ubuntu 24.04 and above cannot start

In Ubuntu 24.04 and above, the system defaults to stricter non-privileged user namespace restrictions. Some AppImage applications may fail to start due to Electron / Chromium sandbox initialization failure.

If you encounter a similar error when running AppImage:

The SUID sandbox helper binary was found, but is not configured correctly

or promptchrome-sandboxPermission exception, you can try to start with the following command:

./OneKey-Wallet-*.AppImage --no-sandbox

Please ensure the command is run in the directory where the AppImage file is located.

Common Questions

AppImage prompts missing X Server or DISPLAY

If you encounter an error about missing X Server or$DISPLAY, it usually indicates that the current system lacks a graphical desktop environment or related components.

For Ubuntu / Debian systems, you can install the relevant graphical environment components and then try to run again.

Hardware wallet not recognized after configuring udev rules

Please check in order:

Have you reconnected the hardware wallet
Have you runsudo udevadm control --reload-rules
Have you run sudo udevadm trigger
Has the OneKey App obtained USB access permission

If you are using the Snap version, please confirm that you have run:

sudo snap connect onekey-wallet:raw-usb

How to Install OneKey App on Linux Systems