🟩 BedrockOnLinux

Run Minecraft Bedrock for Windows (GDK edition) on Linux with native Microsoft/Xbox identity, multiplayer, friends and Realms.

Latest release · Report a bug · MIT license

Ubuntu · Debian · Linux Mint / LMDE · Fedora · Arch · openSUSE

---

What 2.0 provides

BedrockOnLinux installs the Minecraft version you select, prepares a managed Wine prefix and runs the game through a reviewed WineGDK-based GDK-Proton engine. No compiler or Windows installation is required on the player’s machine.

• Native Xbox identity: XGame configuration, XUser, request signatures, gamertags, privileges and the XSAPI context are implemented by WineGDK.
• Online play: the Friends list, invitations, joining friends, public servers and Realms use that native identity. Realms receives a dedicated XSTS token for the Bedrock Realms audience instead of a generic Xbox token.
• No Minecraft memory patcher: the managed engine contains no code that scans or rewrites the running Minecraft process. Packaging rejects remnants of the former process-memory implementation. Static, fingerprinted game and Proton compatibility fixups are still applied before launch.
• Working native file chooser: the WinAppSDK file picker used by Minecraft is implemented in Wine for both Windows architectures, including single and multiple selection. In-game world and skin selection opens the desktop file dialog instead of terminating the game.
• Graphics safety: the launcher checks the existing display state and text kernel logs without opening Vulkan or OpenGL. A known unsafe session is blocked before Wine starts.
• Verified updates: engine archives, critical runtime files and dependency payloads are SHA-256 pinned. A rejected update does not replace a working engine.

The Microsoft sign-in flow runs locally between the launcher, Microsoft and Xbox services. BedrockOnLinux does not use an account relay or multiplayer proxy.

Install

Download application files from the latest release. All currently supported builds target x86-64 Linux.

Format	Best for	Start command
AppImage	Most glibc-based desktop distributions	./BedrockOnLinux-*-x86_64.AppImage
.deb	Debian, Ubuntu, Mint and LMDE	sudo apt install ./bedrock-on-linux_*_amd64.deb
Portable .pyz	A host with Python 3.9+ and Tk	./bedrock-on-linux-*.pyz gui
Flatpak bundle	Sandboxed local installation, when provided	flatpak install --user ./BedrockOnLinux-*-x86_64.flatpak

AppImage quick start

chmod +x BedrockOnLinux-2.0.0-x86_64.AppImage
./BedrockOnLinux-2.0.0-x86_64.AppImage

The first PLAY needs the matching engine archive:

GDK-Proton-xuser-<engine-revision>.tar.gz

With an internet connection, the launcher downloads the exact archive from the BedrockOnLinux release automatically. You can instead keep that engine asset beside the AppImage or .pyz; a matching local sidecar is preferred and verified before extraction. This is required when testing an unpublished candidate and is useful for an offline first install.

An existing installation is upgraded in the same way on its next PLAY. The launcher validates the new engine before an atomic replacement and keeps the previous tree if download, disk space, extraction or verification fails. The fix is therefore distributed to existing users as well as fresh installs.

If FUSE is unavailable, AppImage can extract itself at runtime:

APPIMAGE_EXTRACT_AND_RUN=1 ./BedrockOnLinux-2.0.0-x86_64.AppImage

The AppImage bundles Python, Tk, the GUI toolkit, cryptography and CA certificates. It still uses the host graphics driver and common X11, Xft and fontconfig libraries. The .deb declares its host dependencies; the portable .pyz uses the host Python environment and can install its pinned Python GUI and sign-in dependencies on first use.

Flatpak is built separately when a builder is available. See flatpak/README.md for local build and permission details; the presence of a manifest does not imply that a particular release is already published on Flathub.

Requirements and limitations

• An x86-64 glibc desktop. The AppImage and managed engine are audited against a glibc 2.31 baseline. ARM and musl-only systems such as stock Alpine are not supported.
• X11 or XWayland for the launcher GUI. The game normally uses X11/XWayland. Native Wine Wayland can be tried with BOL_INPUT=wayland, but remains an experimental game backend; it does not remove the launcher’s XWayland requirement.
• A working Vulkan 1.3 driver exposing VK_EXT_device_generated_commands, or the older NVIDIA VK_NV_device_generated_commands. The managed vkd3d-proton 3.0.1 payload contains both implementations and chooses inside the game process.
• Enough free storage for the game, compressed engine and temporary extraction. A No space left on device error is non-destructive: free space and retry PLAY.
• A Microsoft account entitled to Minecraft. Friends, multiplayer and Realms also depend on the account’s privacy settings, any required Realms subscription or invitation, and the availability of Microsoft/Xbox/Minecraft services.

The launcher is an independent compatibility project and is not affiliated with or supported by Mojang or Microsoft. Minecraft updates can change private game interfaces; select a known-working version or attach diagnostics when a new version regresses.

Play

1. Open BedrockOnLinux.
2. Select Sign in, open the Microsoft device-code page shown by the launcher and enter its code.
3. Select a Minecraft version, then choose ▶ PLAY.
4. Use Minecraft’s Friends, Servers and Realms tabs normally.

The first run downloads and prepares Minecraft, then downloads and verifies the managed engine and its online/TLS compatibility payload. Later runs reuse them. Account credentials are stored in the private BedrockOnLinux data directory and seeded into the stopped Wine prefix before launch.

Minecraft’s Import World and skin-selection actions use the WineGDK native file picker. For direct launcher-side content installation while Minecraft is closed, use:

bedrock-on-linux import world.mcworld addon.mcaddon pack.mcpack template.mctemplate

The launcher imports .mcworld, .mcaddon, .mcpack and .mctemplate archives into the appropriate com.mojang directory. It does not overwrite an existing item with the same folder name.

GPU safety

BedrockOnLinux deliberately does not open a Vulkan or OpenGL device to guess whether the driver is healthy. Before launch it can detect, from already available state, conditions such as:

• an X11 session with no hardware RandR provider;
• FBDEV or software-rendering fallback;
• a fatal graphics-driver event in the kernel journal;
• a Minecraft GPU session that did not return before a reboot or power loss.

The last case is recorded by a durable launch marker. A normal completed shutdown retires it only after the Wine prefix is idle. Version 2.0 records a separate durable wrapper-return phase, so a delayed normal Wine teardown no longer becomes a permanent same-boot block. Older markers cannot distinguish the userspace crash reported in issue #31 from a real driver failure and therefore still require the explicit one-time acknowledgement below.

If the desktop freezes or the machine requires a forced power-off, do not blindly retry. Repair or reinstall the host GPU driver, reboot, then run:

bedrock-on-linux doctor
bedrock-on-linux doctor --acknowledge-gpu-crash

Acknowledgement clears only an old interrupted-session block. A current kernel fault or unsafe display state remains blocked. The advanced override below is intended only for a confirmed false positive and can re-expose a kernel hard lock:

BOL_ALLOW_UNSAFE_GPU=1 bedrock-on-linux play

Diagnostics and recovery

Open Settings ▸ Open logs folder, or inspect:

~/.local/share/bedrock-on-linux/logs/

The GUI’s Details panel contains the live launcher log. Useful commands:

bedrock-on-linux doctor                 # host dependencies and GPU safety
bedrock-on-linux repair                 # rebuild the managed Wine prefix
bedrock-on-linux versions               # available stable versions
bedrock-on-linux versions --beta        # include beta versions
bedrock-on-linux setup --mc <version>   # download and prepare one version
bedrock-on-linux login                  # link a Microsoft account
bedrock-on-linux play                   # launch the selected version
bedrock-on-linux update                 # check for a launcher update

repair resets compatibility state, not the host graphics driver. Back up any important game data before manual changes under ~/.local/share/bedrock-on-linux. When reporting a bug, include the launcher version, engine revision, Minecraft version, distribution, GPU/driver and the relevant log files; never publish account tokens or the private authentication directory.

Engine integrity and source provenance

The managed engine is not built on the user’s computer. Release maintainers produce it from pinned inputs and the launcher accepts only the revision and archive SHA-256 recorded in bol/config.py.

• WineGDK is built in an unprivileged Debian 11 (Bullseye) chroot. Every resulting ELF is rejected if it requires a glibc symbol newer than 2.31.
• The exact WineGDK source commit, reviewed patches and changed-file hashes are stored under third_party/.
• The universal vkd3d-proton build contains reviewed EXT-DGC and restored NV-DGC variants for x86-64 and i386. Its inputs and output hashes are documented in third_party/vkd3d-proton-universal/README.md.
• scripts/package-engine.sh embeds licences, build records, source provenance and an engine-manifest.json that hashes critical runtime files. The completed archive is extracted and rechecked before it is accepted as a candidate.
• Engine installation uses a lock and transactional rename. An interrupted or invalid update cannot silently become the active managed engine.

The native Xbox and WinAppSDK work is built for both PE architectures. The packager verifies native XGame/XUser markers, file-picker registration and the absence of the former memory-patcher code before creating the archive.

Build from source

Application builds require the matching engine and OpenSSL XCurl assets to already be present in dist/; release scripts do not download or publish unreviewed substitutes.

# Build the pinned WineGDK source in a clean Bullseye work directory.
scripts/build-winegdk-bullseye.sh /path/to/empty-workdir /path/to/WineGDK

# Build the reviewed universal vkd3d-proton payload when it is not available.
scripts/build-vkd3d-universal.sh /path/to/empty-vkd3d-workdir

# Package the engine from reviewed inputs and the WineGDK build prefix.
scripts/package-engine.sh \
  /path/to/staged/GDK-Proton-xuser \
  /path/to/vkd3d-proton-3.0.1-universal-dgc \
  "$(python3 -c 'from bol.config import WINEGDK_SOURCE_COMMIT; print(WINEGDK_SOURCE_COMMIT)')" \
  /path/to/GDK-Proton10-32.tar.gz \
  /path/to/empty-workdir/prefix

# Build and verify .deb, AppImage, portable .pyz and local/dev Flatpak candidates.
scripts/build-release.sh
scripts/verify-release-candidate.sh

# Force-install the exact local sidecar and run it; never publishes anything.
scripts/run-candidate.sh gui

# Optional standalone local/dev Flatpak rebuild. For publication, pin the
# release tag and commit in the manifest, then add --release.
scripts/build-flatpak.sh

scripts/build-release.sh only creates local candidate files and checksums in dist/; its Flatpak is intentionally a working-tree development bundle. It does not tag, push or upload a release. Bump the engine revision whenever engine contents or packaging change, update the reviewed archive hash in bol/config.py, run the complete test suite and smoke-test the exact candidate before publication.

Legal and license

BedrockOnLinux ships no Minecraft game files. By default, game packages are obtained from the community-maintained bubbles-wow/mcbe-gdk-unpack-archive, or from a local source selected by the user. You must own Minecraft and comply with the terms that apply to it.

WineGDK, GDK-Proton, vkd3d-proton and bundled dependencies remain under their respective licences; the engine includes their relevant notices and provenance. BedrockOnLinux itself is MIT-licensed — see LICENSE.