-
-
Notifications
You must be signed in to change notification settings - Fork 56
0. FAQ
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.
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
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.
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.
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.
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
lsusbin a terminal. You should see an Elgato device listed.
Yes, but not for the same device at the same time. You have two options:
- Use them for different devices: If you have multiple Stream Decks, each app can control a different one.
- 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.
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
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.
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".
Yes! Simply copy your entire OpenDeck config directory to back up all your profiles, plugin settings, and configuration.
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)]
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)
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.
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
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.
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.
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/nodeReplace <version> with your Node.js version (e.g., v22.14.0).
- Install the Discord plugin from OpenDeck's plugin store, not from Elgato
- Make sure Discord is running
- Press a Discord plugin button – it will ask you to authorize in Discord
- If it breaks after some time, try this:
- Quit OpenDeck
- Remove the ESD authorization in Discord settings
- Quit Discord
- Delete
~/.config/opendeck/settings/com.elgato.discord.sdPlugin.json - Open Discord, then OpenDeck, and authorize again
You can access logs directly from OpenDeck:
- Open OpenDeck Settings
- Click "Open log directory"
The logs directory contains:
-
opendeck.log– Main application log -
plugins/folder – Individual plugin logs
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
opendeckWarning: This will delete all your profiles and settings!
- 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)
# Standard install:
/bin/opendeck
# Flatpak:
flatpak run me.amankhanna.opendeckRunning from terminal helps you see error messages that might explain issues.
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
- Stream Deck+: Button support is complete. Dial support is available in recent versions.
- Stream Deck Neo: Button support works. Touch point and LCD screen support is being worked on.
- Touch screens and LCD strips: Limited support; development is ongoing.
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.
Automatic profile switching (changing profiles based on the active window) is available and works on both X11 and Wayland (via XWayland detection).
Currently, animated GIFs are not supported – they will display as a static image showing the first frame.
OpenDeck supports official Elgato Stream Deck devices:
- Stream Deck Mini
- Stream Deck MK.1 and MK.2
- Stream Deck XL
- Stream Deck+ (limited support for the touch strip)
- Stream Deck Neo (buttons work, touch features in development)
- Stream Deck Pedal
Non-Elgato devices: OpenDeck focuses on Elgato devices. Third-party macro pads typically require installing a community-supported plugin.
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!
This FAQ was last updated in December 2025.