How to Fix LocalWP Not Opening on Linux (Fedora 44 / Wayland / Gnome)
If you’ve recently installed LocalWP on Fedora or any modern Wayland-based Linux distribution, you may have encountered a frustrating issue: you click the application icon, see a brief loading spinner, and then... nothing happens.
Even worse, running the binary from the terminal might show that the Node.js backend initializes successfully (Electron Event ready), yet no graphical window ever pops up on your screen.
This issue is caused by three main factors:
- Corrupted JSON configuration cache from aborted startups.
- Chromium/Electron Wayland display server incompatibilities.
- Hardware GPU acceleration glitches under modern Linux graphics pipelines.
Here is the exact, tested, step-by-step fix to get LocalWP running smoothly on your machine.
Step 1: Diagnose the Process in Terminal
Before applying fixes, run LocalWP directly from your terminal to see if the process is stuck or throwing errors:
/opt/Local/local
If your output hangs around Electron Event ready without showing a UI window, or if it throws a SyntaxError: Unexpected end of JSON input error, move to the next steps.
Step 2: Clear Corrupted Configuration Files
When LocalWP crashes during initial launches, it often leaves behind empty or malformed JSON files in your local user directory (~/.config/Local/). These corrupted files block the UI renderer process.
Run the following commands to clean up the application state cache without touching your WordPress site files:
# Kill any hidden background Local processes
killall local
# Remove corrupted hub config and GPU/window state caches
rm -f ~/.config/Local/hub-api.json
rm -rf ~/.config/Local/GPUCache ~/.config/Local/Local-Storage ~/.config/Local/"window-state.json"
Step 3: Launch with Wayland and No-Sandbox Flags
Modern Linux distributions like Fedora run Wayland by default instead of legacy X11, while LocalWP uses an older version of Electron that requires explicit flags to render correctly under Wayland without GPU hardware acceleration hangs.
Test launching LocalWP using the following flags:
/opt/Local/local --no-sandbox --disable-gpu --enable-features=UseOzonePlatform --ozone-platform=wayland
Your LocalWP application window should now instantly pop up and function normally!
Step 4: Make the Fix Permanent (No Terminal Required)
You don't need to run this long terminal command every time you want to open LocalWP. You can update your desktop launcher shortcut so it opens directly from your Application Menu/Dash.
1. Copy the system desktop entry to your local user directory:
cp /usr/share/applications/local.desktop ~/.local/share/applications/
2. Open the desktop file for editing:
nano ~/.local/share/applications/local.desktop
3. Update the Exec= line:
Find the line that starts with Exec= and append the required flags to the end:
Exec=/opt/Local/local %U --no-sandbox --disable-gpu --enable-features=UseOzonePlatform --ozone-platform=wayland
4. Save and Exit:
Press Ctrl + O, then Enter to save, and Ctrl + X to exit.
Step 5: (Bonus) Fix Nginx Port Binding Permissions
If LocalWP gives you a Router Mode error when attempting to run sites on standard HTTP ports (80/443), give Local's bundled Nginx binary net-bind permission:
sudo setcap cap_net_bind_service=+ep ~/.config/Local/lightning-services/nginx-*/bin/linux/sbin/nginx
Alternatively, you can switch LocalWP to localhost mode in Preferences > Advanced > Router Mode > Localhost.
Summary
By cleaning out corrupted Electron session state files and passing modern Ozone/Wayland rendering flags (--ozone-platform=wayland --disable-gpu), you can run LocalWP seamlessly on Fedora and modern Linux distributions without terminal hacks on every launch.
Author & Connect
Written by Sakib Ahmed (Software Engineer)
- GitHub: github.com/devvsakib
- LinkedIn: linkedin.com/in/sakibahmed5
#LocalWP #Fedora #Linux #Wayland #Electron #WordPress #WebDevelopment #DevOps #SakibAhmed #devvsakib
Top comments (0)