Automattic · ivan-ottinger · May 21, 2026 · May 21, 2026 · May 21, 2026 · May 21, 2026
diff --git a/README.md b/README.md
@@ -10,12 +10,13 @@ Spin up sites in seconds, sync with WordPress.com or Pressable, or import any Wo
 
 ## Get started
 
-WordPress Studio is free to use for Mac and Windows. Simply download the app to start building and testing — no dependencies required.
+WordPress Studio is free to use for Mac, Windows, and Linux. Simply download the app to start building and testing — no dependencies required.
 
 [Download WordPress Studio](https://developer.wordpress.com/studio/) for:
 
 - macOS (Intel or Apple Silicon)
-- Windows
+- Windows (x64 or ARM64)
+- Linux (x64 or ARM64)
 
 ## Highlights
 

diff --git a/docs/code-contributions.md b/docs/code-contributions.md
@@ -196,7 +196,7 @@ Then open `chrome://inspect` in a Chromium-based browser and click "inspect" nex
 ## Building Installers
 
 Once all required dependencies are installed, you can build installers for the app.
-Installers can currently be built on Mac (Intel or Apple Silicon), Windows, and experimentally for Linux using the following commands:
+Installers can be built on Mac (Intel or Apple Silicon), Windows (x64 or ARM64), and Linux (x64 or ARM64) using the following commands:
 
 ```bash
 npm install
@@ -205,24 +205,7 @@ npm run make
 
 After the build process completes, you can find the executables in the `out/` directory.
 
-### Linux
-
-Linux support is currently in an experimental phase. While official packages are not yet available, you can build Studio from source:
-
-```bash
-npm install
-npm run package
-```
-
-After building, the executable will be located at `apps/studio/out/Studio-linux-x64/studio`.
-
-**Important considerations:**
-
-- The auto-update feature is not currently supported on Linux builds.
-- For Wayland systems, you may need to use additional flags when running the application.
-- Some features may not work as expected due to platform-specific implementations.
-
-For detailed instructions including how to create a desktop launcher, handle Wayland compatibility, and troubleshoot common issues, see the [**Linux Guide**](./linux.md).
+Linux has additional source-build steps and platform-specific troubleshooting — see the [Linux notes](./linux.md).
 
 ## Localization
 

diff --git a/docs/linux.md b/docs/linux.md
@@ -1,146 +1,74 @@
-# Linux Guide
+# Linux
 
-Studio for Linux is currently in an experimental phase. While official packages are not yet available, you can easily build and run Studio from source on most Linux distributions.
-
-## Current Limitations
-
-Linux support comes with certain limitations:
-- For systems using Wayland, you may need to set the `--enable-features=UseOzonePlatform --ozone-platform=wayland` flag when running the application.
-- Some features may not work as expected on Linux due to platform-specific implementations.
-- The auto-update feature is not currently supported on Linux builds.
-- These instructions should work for most Linux distributions, but you may need to adjust them based on your specific setup or distribution.
+Linux-specific build steps and troubleshooting for contributors. See also [code-contributions.md](./code-contributions.md) for general setup.
 
 ## Building from Source
 
-### Prerequisites
-
-Ensure you have the following dependencies installed:
-
-- [Node.js](https://nodejs.org/) - required JavaScript runtime environment
-- [Python](https://www.python.org/) - required for building native dependencies
-- [setuptools](https://pypi.org/project/setuptools/) - required for building native dependencies
-
-Many contributors use [`nvm`](https://github.com/nvm-sh/nvm) to manage Node.js installations.
-
-### Build Steps
-
-1. **Clone the repository:**
-   ```bash
-   git clone https://github.com/Automattic/studio.git
-   cd studio
-   ```
-
-2. **Install dependencies:**
-   ```bash
-   nvm use
-   npm install
-   ```
-
-3. **Build the application:**
-   ```bash
-   npm run package
-   ```
-
-   This will create an `out/` folder inside `apps/studio/`.
+To build a runnable app bundle from a clone:
 
-4. **Locate the executable:**
-
-   Navigate to the `apps/studio/out/Studio-linux-x64/` folder. Inside, you'll find a `studio` executable.
-
-5. **Run Studio:**
-   ```bash
-   cd apps/studio/out/Studio-linux-x64
-   ./studio
-   ```
-
-## Creating a Desktop Shortcut (Optional)
-
-For easier access, you can create a desktop entry file that will add Studio to your application launcher.
+```bash
+npm install
+npm run package
+```
 
-### Steps
+The executable will be at `apps/studio/out/Studio-linux-<arch>/studio`. To produce a `.deb` package instead, run `npm run make` (auto-detects the host arch); output lands in `apps/studio/out/make/deb/<arch>/`. To make arch specific build, use `npm run make:linux-x64` or `npm run make:linux-arm64
 
-1. **Create a desktop file:**
-   ```bash
-   nano ~/.local/share/applications/studio.desktop
-   ```
+## Creating a Desktop Shortcut
 
-2. **Add the following content:**
-   ```ini
-   [Desktop Entry]
-   Name=Studio by WordPress.com
-   Icon=<absolute-path-to-repo>/assets/studio-app-icon.png
-   Comment=Local WordPress development environment
-   Exec=<absolute-path-to-repo>/apps/studio/out/Studio-linux-x64/studio %U
-   Type=Application
-   Terminal=false
-   MimeType=x-scheme-handler/wp-studio;
-   Categories=Development;
-   ```
+`.deb` installs register a desktop entry automatically. For source builds you can create one manually:
 
-3. **Replace placeholders:**
-   - Replace `<absolute-path-to-repo>` with the actual absolute path to your cloned repository
-   - For example: `/home/username/projects/studio`
+```bash
+nano ~/.local/share/applications/studio.desktop
+```
 
-4. **Make the desktop file executable (if needed):**
-   ```bash
-   chmod +x ~/.local/share/applications/studio.desktop
-   ```
+Add the following, replacing `<absolute-path-to-repo>` with the actual path to your clone and `<arch>` with `x64` or `arm64` to match your build:
 
-5. **Refresh your application menu:**
-
-   Depending on your desktop environment, you may need to log out and back in, or run:
-   ```bash
-   update-desktop-database ~/.local/share/applications
-   ```
+```ini
+[Desktop Entry]
+Name=Studio by WordPress.com
+Icon=<absolute-path-to-repo>/apps/studio/assets/studio-app-icon.png
+Comment=Local WordPress development environment
+Exec=<absolute-path-to-repo>/apps/studio/out/Studio-linux-<arch>/studio %U
+Type=Application
+Terminal=false
+MimeType=x-scheme-handler/wp-studio;
+Categories=Development;
+```
 
-6. **Register Studio handler for `wp-studio://` links:**
-   ```bash
-   xdg-mime default studio.desktop x-scheme-handler/wp-studio
-   ```
-   Without this, browsers will still show "Open With… / No Apps Available" when WordPress.com OAuth redirects back to `wp-studio://`.
+After creating the file, refresh the application menu so the entry appears:
 
-Studio should now appear in your application launcher and can handle `wp-studio://` protocol URLs.
+```bash
+update-desktop-database ~/.local/share/applications
+```
 
-## Running with Wayland
+## Registering the `wp-studio://` URL handler
 
-If you're using Wayland instead of X11, run Studio with additional flags:
+When working on OAuth/login flows from a source build, register the binary as the `wp-studio://` handler so browser callbacks reach your dev build:
 
 ```bash
-./studio --enable-features=UseOzonePlatform --ozone-platform=wayland
+xdg-mime default studio.desktop x-scheme-handler/wp-studio
 ```
 
-You can add these flags to the `Exec` line in your desktop file if you created one:
-
-```ini
-Exec=<absolute-path-to-repo>/apps/studio/out/Studio-linux-x64/studio --enable-features=UseOzonePlatform --ozone-platform=wayland %U
-```
+This depends on the `.desktop` file from the previous section. Without it, browsers will show "Open With… / No Apps Available" when WordPress.com OAuth redirects back, or hand the callback off to an installed `.deb` build (masking the bug you're trying to debug).
 
 ## Troubleshooting
 
-### Permission Issues
-
-If you encounter permission issues when running the executable, make sure it has execute permissions:
+If `./studio` fails with a permission error, ensure it has execute permissions:
 
 ```bash
-chmod +x apps/studio/out/Studio-linux-x64/studio
+chmod +x apps/studio/out/Studio-linux-<arch>/studio
 ```
 
-### `npm start` fails with a Chrome sandbox error (Ubuntu 24.04+)
-
-On distributions that restrict unprivileged user namespaces via AppArmor (notably Ubuntu 24.04+), `npm start` may abort with `FATAL: ... The SUID sandbox helper binary was found, but is not configured correctly`. Electron falls back to its SUID sandbox because AppArmor blocks the user-namespace sandbox by default.
-
-Allow the user-namespace sandbox persistently:
+On Ubuntu 24.04+ and other distributions that restrict unprivileged user namespaces via AppArmor, `npm start` may abort with `FATAL: ... The SUID sandbox helper binary was found, but is not configured correctly`. Electron falls back to its SUID sandbox because AppArmor blocks the user-namespace sandbox by default. Allow it persistently:
 
 ```bash
 echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/60-apparmor-namespace.conf
 sudo sysctl --system
 ```
 
-The setting survives reboots and `npm install` runs, so you only need to do this once per machine.
-
-### Missing Dependencies
+The setting survives reboots and `npm install` runs, so you only need to do this once per machine. This only affects `npm start` during development; installed `.deb` packages ship a properly-configured SUID sandbox binary and are unaffected.
 
-If you encounter errors about missing libraries, you may need to install additional system dependencies. Common packages include:
+If you encounter errors about missing libraries on a source build (`.deb` installs declare their dependencies automatically), install the common system packages:
 
 ```bash
 # Debian/Ubuntu
@@ -152,26 +80,3 @@ sudo dnf install gtk3 libnotify nss libXScrnSaver libXtst xdg-utils at-spi2-core
 # Arch
 sudo pacman -S gtk3 libnotify nss libxss libxtst xdg-utils at-spi2-core util-linux libsecret
 ```
-
-## Updating Studio
-
-Since auto-updates are not supported on Linux builds, you'll need to manually update:
-
-1. Pull the latest changes from the repository:
-   ```bash
-   cd <path-to-repo>
-   git pull
-   ```
-
-2. Reinstall dependencies and rebuild:
-   ```bash
-   npm install
-   npm run package
-   ```
-
-The executable in `apps/studio/out/Studio-linux-x64/` will be updated with the new version.
-
-## Contributing
-
-If you encounter Linux-specific issues or have suggestions for improving Linux support, please [open an issue](https://github.com/Automattic/studio/issues) or submit a pull request. Your feedback helps improve Studio for all Linux users!
-