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 has been supported since 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.1.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	The display runtime for Linux exists - it switches the lens into 3D and runs the eye tracking - but it is not published anywhere for end users to install, and its license terms are unknown. Every route to these displays needs it, so glasses-free output stays on Windows until the vendor makes it available.
HDR output	An HDR film or photo is sized against how bright your screen can go, and on Linux the graphics layer Oku3D draws through does not report that. Without it there is nothing to measure against, so HDR plays at ordinary brightness here.
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.
Frame Packing	The 3D resolution (1920x2205 for films, 1280x1470 for everything else) has to be in the display's mode list on any graphics card; the automatic setup on NVIDIA cards exists only on Windows. In an X11 session Oku3D then switches the display into it when you go fullscreen. On Wayland no application may change the display mode, so set that resolution in your desktop's display settings before you start.
Audio device changes	A device that appears or disappears is picked up within a second or two rather than instantly.
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.
A 3D TV or projector with an HDMI 3D input. Frame Packing has only been tried on Windows so far - a projector switched into 3D, a TV that waits for the HDMI 3D marking stayed flat. Does your display switch into 3D from a Linux machine - in an X11 session on its own, or on Wayland with the 3D resolution set beforehand? Name the graphics card too: whether the display gets the HDMI 3D marking some TVs wait for depends on the driver.
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.