Oku3D on Linux

What you need, which download to take, what runs and what does not, and which combinations still need a second pair of eyes.

Table of Contents

Download
What you need
Which download
Installing
Linux vs. Windows
Where I need help

Download

Linux support is new in 3.0.0. One build, three shapes of it, from the same run. Which one to take depends on your system, not on what you want from the player.

Archive (.tar.gz)Unpack anywhere - the plain choice AppImageOne file, mark it executable, run it FlatpakFor Steam Deck and Steam Machine

Version 3.0.0, 64-bit x86 - no ARM build. What is new in this release.

What you need

Item	Needs
Processor	64-bit x86 - what ordinary PCs and laptops run, also written x86-64 or amd64. There is no ARM build, so a Raspberry Pi, a Snapdragon laptop or an Apple-silicon Mac under Linux cannot run it. A Pi would not clear the graphics requirement below in any case.
Distribution	Ubuntu 24.04 LTS or newer, or any distribution released from 2024 onward. Older ones are missing system libraries the build needs.
Graphics	A working Vulkan driver. AMD and Intel have one out of the box on any current distribution; NVIDIA needs its proprietary driver.
GPU	Any card from roughly 2016 onward, with 4 GB of video memory for the 2D-to-3D conversion and 8 GB for comfort.
Session	Wayland or X11. Wayland is what the build is developed on.

The 2D-to-3D conversion runs on the graphics card through Vulkan, so it does not depend on the vendor - AMD, Intel and NVIDIA all convert on the GPU rather than the processor. There is no CUDA requirement.

Which download

All three carry the same program and register the same file associations. They differ only in how they get onto your system.

Format	Take it if
Archive	You are on an ordinary desktop. Unpack it anywhere and run the included install script, which you can read first. The plainest option and the one with the fewest moving parts.
AppImage	You want one file and nothing installed. Mark it executable and double-click. Nothing touches your system until you ask it to.
Flatpak	Your system will not let you install anything else - the Steam Deck and the Steam Machine boot a read-only system where Flatpak is the supported way. It works anywhere, but on a desktop that can simply unpack the archive it buys nothing and costs two things.

Installing

AppImage

Mark it executable (chmod +x, or the Permissions tab in your file manager) and run it. To get the desktop entry and file associations, use the archive instead - an AppImage deliberately installs nothing.

Flatpak

Install the downloaded file with flatpak install ./oku3d-*.flatpak, then start it from your menu or with flatpak run com.oku3d.Oku3D.

Two things the Flatpak costs

VR output needs one command. A sandboxed application cannot reach a VR runtime on its own, and there is no standard way to grant it. What it needs is access to the runtime's own files, which the sandbox deliberately keeps applications from reading. For WiVRn installed for your user:

flatpak override --user com.oku3d.Oku3D \
    --filesystem=~/.local/share/flatpak/app/io.github.wivrn.wivrn:ro \
    --filesystem=xdg-run/wivrn:ro

Another runtime needs its own two paths. A runtime installed as a system package rather than as a Flatpak cannot be reached this way at all. The archive and the AppImage have no such limit.

It brings its own graphics driver. A Flatpak ships with the graphics stack of its runtime instead of using the one the rest of your desktop uses, so the picture can differ from the archive's on the very same machine. The diagnostics report (Ctrl+P) names the driver and its version, which is the first thing to compare if something looks off.

Where Linux and Windows differ

The player behaves the same way on either one. These are the places where the system underneath shows through.

Only on Linux

Feature	What you get
Media keys and desktop controls	The keyboard's play, pause and skip keys reach the player, the shell's media widget shows what is playing and can control it, the lock screen does the same, and `playerctl` works. Windows has an equivalent that is not built yet.

Only on Windows

Feature	Why not here
Glasses-free 3D	A kit for Linux exists. What is missing is everything around it: the display runtime has no public route for end users to install it, switching the lens on in a shipped application depends on keys the vendor holds, and the license terms are unanswered.
Game overlay	It needs two things, and no Linux desktop offers both. Putting a window above everything else needs a protocol GNOME does not implement. The key combination that switches it has to work while another application has focus, which GNOME and KDE allow and the other desktops do not.
Clicks from VR	It rests on injecting a real click into another application, which an application may not do on its own here. Screen capture itself works; only clicking back into what it shows does not.
Bitstream audio	The player already produces the right data. The problem is that nothing on the Linux audio side can be asked whether an output will carry it: opening the device always succeeds, analog outputs included, and if the marking does not reach the hardware the data is played as sound - loud noise at whatever volume was set. Windows refuses instead, which is what makes it safe there. One tester with a receiver would unblock this.

Same feature, different in practice

Listed because they can be felt, not because anything is missing.

Feature	On Linux
Screen capture	Your desktop shows its own picker and asks permission every time - that is the only way any application may capture at all here, not something the player adds. It does not remember your answer on purpose: quietly regaining the ability to record your screen should not be a side effect of having recorded once.
Audio device changes	A device that appears or disappears is picked up within a second or two rather than instantly.
Turning a 360° view or a 3D scan	On Wayland the pointer is held in place while you drag, so the turn carries on as long as you keep moving your hand and the cursor comes back where you started. In an X11 session it stops at the edge of the screen instead.
Remembering a setting per image	Settings offers Hidden file attribute where Windows offers a hidden NTFS stream. Same idea and the same limit: the value rides along with the file only as far as the copying tool carries it. The portable `.xmp` sidecar avoids that on either system.

Where I need help

Everything below is built and expected to work. What is missing is not the code but another machine, which I do not own: this one is an AMD card, GNOME on Wayland and a Quest 3 over WiVRn. One report settles any item on the list.

I would like to hear about anything else that behaves differently on yours, listed here or not: the Discord server, or jens@oku3d.com. A report of "it just worked" answers as much as a failure.

An AV receiver over HDMI. The one item that unblocks a feature rather than confirming one: bitstream audio needs a way to ask whether an output will carry it, and this is the measurement that decides how. Even without installing anything, the output of cat /proc/asound/card*/eld#* says whether your receiver announces Dolby Digital or DTS - and that alone is what the feature's safety gate would be built on.
An NVIDIA card. Nothing in the player is bound to a vendor: rendering is Vulkan, the 2D-to-3D conversion is Vulkan, and hardware decoding has a Vulkan route measured working on an AMD card, 10-bit HEVC included. NVIDIA's driver implements the same interfaces, so this should be a formality - it is simply one that no machine here can perform. Open any video and look at the diagnostics report (Ctrl+P): it names which route decoded. Setting OKU3D_HW_DECODE=vulkan before starting forces that route, so a refusal is reported instead of quietly skipped. Worth adding: whether 4K plays smoothly, and what the processor load is.
Intel integrated graphics. The third vendor, and the one most laptops ship with. Same two answers as above - which route decoded, and whether 4K holds up.
An HDMI capture card. A webcam works end to end here, microphone included; a capture card has never been plugged in. Does the picture appear, and does the paired audio device play with it?
A VR headset that is not a Quest over WiVRn. An Index, a Vive or a Pimax on SteamVR or Monado - a headset its runtime drives as a display instead of streaming to it. That is the half WiVRn cannot stand in for.
KDE Plasma as your everyday desktop. Screen capture, revealing a file, the media controls and the idle inhibitor each have more than one implementation behind them, and only GNOME's has been exercised. Whether those four work on Plasma is a question its own users answer fastest.

The in-app diagnostics report (Ctrl+P by default) copies everything a report needs to your clipboard - system, graphics driver and version, audio path, decoder route, and the state of the open file. Pasting that alongside a description is the most useful thing a report can carry. Post it on the Discord server or write to me.