This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Important

If this FAQ solved your problem, we'd still like to hear about it! Knowing which problems users face is very helpful for prioritising what we work on, and what we include on this page.

This FAQ was generated by Claude Opus 4.5, using frequently-asked questions from the OpenDeck Discord server and GitHub Issues as sources.

OpenDeck FAQ

Welcome to the OpenDeck Frequently Asked Questions! This guide addresses the most common questions and issues users encounter when using OpenDeck.

Getting Started
Device Detection
Profiles & "Folders"
Input Simulation (Keyboard Shortcuts)
Plugins
Troubleshooting
Advanced Topics

Getting Started

What is OpenDeck?

OpenDeck is a free, open-source application that lets you use Stream Deck and compatible devices on Linux, macOS, and Windows. It provides button customization, key simulation, plugin support, and much more.

How do I install OpenDeck?

The recommended way to install OpenDeck is by using the official install script:

bash <(curl -sSL https://raw.githubusercontent.com/nekename/OpenDeck/main/install_opendeck.sh)

This will detect your system and install the appropriate package. Alternatively, you can download packages directly from the GitHub Releases page.

Do I need to restart my computer after installing?

Yes! After installing OpenDeck, you should restart your computer. This ensures that the USB device permission rules (udev rules) are properly applied, which is essential for OpenDeck to detect your Stream Deck.

Device Detection

OpenDeck says "No devices detected" – what do I do?

This is one of the most common issues. Here's what to check:

Did you restart your computer after installation? This is the #1 fix. The udev rules that grant permission to access your device require a reboot to take effect.
Is your device properly connected? Try a different USB port or cable.
Are you using another Stream Deck application? Only one application can control a Stream Deck at a time. If StreamController or the Elgato software is running, close it completely before opening OpenDeck.
Check if your system sees the device: Run lsusb in a terminal. You should see an Elgato device listed.

Can I use OpenDeck and StreamController together?

Yes! You can use the OpenDeck plugin in StreamController. Disable Elgato device discovery in OpenDeck settings, then install the OpenDeck plugin in StreamController. This lets StreamController forward actions to OpenDeck.

My device keeps disconnecting and reconnecting

If your device is detected but then shows as disconnected repeatedly:

Check your USB cable and port (USB hubs can sometimes cause issues)
Make sure you don't have conflicting udev rules from other applications
Restart OpenDeck

Profiles & "Folders"

How do I create folders for my buttons?

OpenDeck doesn't have a built-in "folder" feature like the official Elgato software. However, you can achieve the same result using Profiles:

Create a new profile (e.g., "Games")
Set up your buttons in that profile
On your main profile, add a Switch Profile action that navigates to your "Games" profile
In your "Games" profile, add a button with Switch Profile back to your main profile

This effectively creates a folder-like navigation system between different screens.

Where are my profiles stored?

Your profiles are stored in the OpenDeck config directory:

Standard install: ~/.config/opendeck/profiles/
Flatpak install: ~/.var/app/me.amankhanna.opendeck/config/opendeck/profiles/

Each profile is saved as a .json file. You can also access this directory from within OpenDeck by opening Settings and clicking "Open config directory".

Can I backup my profiles?

Yes! Using OpenDeck v2.12.0 and newer, you can back up and restore your configuration from Settings. Using earlier versions, simply copy your entire OpenDeck config directory to back up all your profiles, plugin settings, and configuration.

Input Simulation (Keyboard Shortcuts)

How do I send keyboard shortcuts like Ctrl+C?

Use the Input Simulation action from the Starter Pack plugin. The syntax uses a special format:

To press Ctrl+C:

[k(ctrl,p),k(uni('c'),c),k(ctrl,r)]

Explanation:

k(ctrl,p) – Press (hold down) the Ctrl key
k(uni('c'),c) – Click the 'c' key
k(ctrl,r) – Release the Ctrl key

Another example – Alt+F10:

[k(Alt,p),k(F10,c),k(Alt,r)]

Input Simulation isn't working – what's wrong?

On Wayland (most modern Linux desktops):

When you first use Input Simulation, a permission dialog should appear asking to "Allow remote interaction"
You must click "Allow" for input simulation to work
This permission prompt appears after reboot, so grant it again when asked
If no dialog appears, try restarting your computer

On X11:

Input Simulation should work without additional prompts
If it doesn't work, check the plugin logs (see Troubleshooting)

Why is the Wayland permission not persistent?

This is a known limitation of the underlying system. On Wayland, the "Allow remote interaction" permission currently needs to be granted after each login/reboot. This is being tracked upstream and may be improved in future releases.

Input Simulation is typing everything twice

This issue was resolved in version 2.7.1. Make sure you're running the latest version of OpenDeck and the Starter Pack plugin. If you're still experiencing this:

Update OpenDeck to the latest version
The Starter Pack plugin should update automatically

Can I type special characters or Unicode?

Simple ASCII text works with the t() function:

[t("Hello World")]

For special characters or non-ASCII text on Wayland, a workaround using the clipboard is needed:

Add a Multi-Action
Add Run Command with: printf 'your text here'|wl-copy
Add Input Simulation with: [k(ctrl,p),k(uni('v'),c),k(ctrl,r)]

This copies your text to the clipboard and pastes it.

Plugins

Where do I install plugins from?

Use the built-in Plugin Store! Go to the plugin store within OpenDeck to find and install plugins. Plugins installed this way are often modified to work better with OpenDeck compared to the original Elgato versions.

Important: Don't download .streamDeckPlugin files from Elgato's website and try to install them directly – they may not work or may have compatibility issues.

I get "Node version 20.0.0 or higher is required"

Some plugins require Node.js. If you installed Node.js using nvm or fnm, OpenDeck might not be able to find it. Here's the fix:

Create a symlink so OpenDeck can find Node:

# For fnm:
sudo ln -s ~/.local/share/fnm/node-versions/<version>/installation/bin/node /bin/node

# For nvm:
sudo ln -s ~/.nvm/versions/node/<version>/bin/node /bin/node

Replace <version> with your Node.js version (e.g., v22.14.0).

The Discord plugin isn't connecting

Install the OpenDeck-native Discord plugin from OpenDeck's plugin store, not the plugin developed by Elgato. For further troubleshooting, consult the Discord plugin troubleshooting guide.

Troubleshooting

Where are the log files?

You can access logs directly from OpenDeck:

Open OpenDeck Settings
Click "Open logs"

The logs directory contains:

opendeck.log – Main application log
plugins/ folder – Individual plugin logs

How do I completely reset OpenDeck?

If you need a fresh start:

# Close OpenDeck completely
killall opendeck

# Delete the config directory
rm -rf ~/.config/opendeck

# For Flatpak installations:
rm -rf ~/.var/app/me.amankhanna.opendeck/config/opendeck

# Restart OpenDeck
opendeck

Warning: This will delete all your profiles and settings!

OpenDeck won't open or crashes immediately

Make sure OpenDeck isn't already running (check your system tray)
Try running from terminal to see error messages: /bin/opendeck
If the app opens but shows a blank screen, try a full reset (see above)

How do I run OpenDeck from the terminal?

# Standard install:
/bin/opendeck

# Flatpak:
flatpak run me.amankhanna.opendeck

Running from terminal helps you see error messages that might explain issues.

The app shows multiple tray icons

This can happen with certain system configurations. Make sure:

OpenDeck isn't running multiple times
Autostart isn't creating duplicate instances
Close all instances and restart once

Advanced Topics

Does OpenDeck support dials and touchscreens?

Stream Deck+: Button, dial and touchscreen implementations are all complete.
Stream Deck Neo: Button and touch point support is complete. Infobar LCD support is complete, but only works with certain actions from specialised plugins.

Can I change profiles from the command line?

Yes! You can switch profiles using a terminal command:

/bin/opendeck --process-message '{ "event": "switchProfile", "payload": { "device": "sd-serialnumber", "profile": "Profile Name" } }'

Replace sd-serialnumber with your device serial and Profile Name with the profile you want to switch to. You can find the exact format by looking at a Switch Profile action in OpenDeck.

Does OpenDeck support automatic profile switching?

Automatic profile switching (changing profiles based on the active window) is available and works on X11 sessions, KDE Wayland sessions, and for some applications on other Wayland sessions (via XWayland detection).

It depends on how you're launching OpenDeck at login:

Using OpenDeck's built-in "Start at login" option (in Settings): OpenDeck will automatically start hidden to the system tray - no extra configuration needed.
Using your desktop environment's own autostart settings (e.g. adding it manually in GNOME's Startup Applications, KDE's Autostart, or a similar tool): pass the --hide argument to start minimised to the tray.

Can I use animated GIFs as button icons?

Currently, animated GIFs are not supported – they will display as a static image showing the first frame.

Is my Stream Deck model supported?

OpenDeck supports official Elgato Stream Deck devices:

Stream Deck Mini
Stream Deck MK.1 and MK.2
Stream Deck XL
Stream Deck+
Stream Deck Neo
Stream Deck Pedal

Non-Elgato devices: OpenDeck focuses on Elgato devices. Third-party macro pads typically require installing a community-supported plugin.

Still Need Help?

If your question isn't answered here:

Check the GitHub Issues for similar problems
Join the OpenDeck Discord community for real-time help
Consider starring ⭐ the project on GitHub – it helps!