Guide for Linux VR

Fixing common issues that hinder the VR experience on Linux. Basic setup, performance tweaks and other improvements are included.

Preface

This guide is a collection of issues, explanations, fixes and tweaks, written in no specific order.

Please write a comment if you can provide any missing or incorrect information, hopefully making VR on Linux more accessible.

Requirements

• A working Linux installation
  
• Sufficiently powerful hardware
  
• A VR headset:
  
  • SteamVR-native (least software required):
    
    • Valve Index
      
    • HTC Vive
      
  • Other (less reliable support):
    
    • Oculus Quest
      
    • Oculus Quest 2
      
    • Oculus Rift DK
      
    • Oculus Rift CV
      
    • Oculus Rift S
      
    • PICO 4
      
  
  HMDs that are not listed may not necessarily be incompatible, please comment if you get your model to work.

Basic setup

For SteamVR-native HMDs, this will be sufficient. For other devices, refer to sections Wireless HMDs and Other VR/XR hardware.

1. Use Steam to install SteamVR and start it with your HMD connected
   
2. Follow the on-screen instructions
   
3. Launch a game

Hopefully, this will work out of the box.

If you have trouble getting past the dialogue asking for root access, refer to section SteamVR stuck getting root access on first startup.

Wireless HMDs

For wireless HMDs such as Oculus Quest and Quest 2, use Air Light VR (ALVR)[github.com].

Please be aware that there are issues with this approach:

• Audio streaming does not work, separate headset/earphones are required*
  
• H.265 encoding is not optimal
  
• Bit rates higher than 200 MB/s cause instability

* Potential solution:

Originally posted by k0lor:

From my wired experience using Quest 2, if you use pipewire, it is possible to manually route the audio using a patchbay (e.g. helvum, Carla).

On ALVR nightly (compiled), set "game audio" as "system default" (microphone on default crashes my system for some reason, but "jack" works). When playing a game, open the patchbay and connect the game output to the "Pipewire ALSA" input that is created.

If you want to connect microphone, you connect a source that gets created (name is random) to the game input.

I only tested on VRChat. You need to reroute the microphone input every time you enter a map/HMD sleeps, because the source disappears

Other VR/XR hardware

For HMDs unsupported by SteamVR out of the box or ALVR, you may need to use Monado[monado.freedesktop.org] and/or OpenHMD[github.com].

This guide does not go over the setup yet.

NVIDIA: Use proprietary drivers

The open source nouveau drivers aren't feature-complete and don't perform well yet (however, that will change soon![www.collabora.com]). Some distributions like Pop!_OS or Linux Mint let you install proprietary NVIDIA drivers during the initial installation setup.

Instructions for Ubuntu-based distributions

• Use this command to list compatible drivers:
  

  ubuntu-drivers devices

• Install the latest available driver (ex. 510):
  

  sudo apt install nvidia-driver-510

• Either restart X or reboot your computer
  
• Use this command to verify whether the drivers have been installed correctly:
  

  nvidia-smi

AMD: Using alternative Vulkan drivers

Note: Games that use OpenGL may not work if a Vulkan driver other than RADV is used, in which case the display will be garbled.

Depending on the driver, some games crash before anything is rendered, and some games have performance benefits. Experiment with each game separately to find the optimal combination.

Short overview of Vulkan drivers

TODO: Test RADV vs AMDVLK again, RADV seems to have significantly advanced in the meantime

• RADV
  
  • Required by SteamVR
    
  • Open source
    
  • Ships with Mesa
    
  • Generally performs worse
    
• AMDVLK
  
  • Open source
    
  • May perform better than RADV
    
  • Games may crash if Proton 8 or newer is selected
    
• AMDGPU-PRO
  
  • Proprietary equivalent of AMDVLK
    
  • May perform better than RADV
    

Instructions

1. Install AMDVLK drivers and optionally AMDGPU-PRO drivers, however the latter should not be installed system-wide, instead use amdgpu-pro-vulkan-only[github.com]
   
2. Since AMD_VULKAN_ICD causes issues (more on that here[gitlab.com]), add these entries to /etc/environment, making RADV the default driver in the process:
   

   DISABLE_LAYER_AMD_SWITCHABLE_GRAPHICS_1=1
   VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/radeon_icd.i686.json:/usr/share/vulkan/icd.d/radeon_icd.x86_64.json

3. In order to use AMDVLK or AMDGPU-PRO Vulkan drivers for games, set these variables only for the games (not SteamVR), appending %command% if it's a Steam game launch argument:
   
   • AMDVLK:
     

     VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/amd_icd32.json:/usr/share/vulkan/icd.d/amd_icd64.json

   • AMDGPU-PRO (depends on where it's installed):
     

     VK_ICD_FILENAMES=/opt/amdgpu-pro/etc/vulkan/icd.d/amd_icd64.json:/opt/amdgpu-pro/etc/vulkan/icd.d/amd_icd32.json

Reprojection

Reprojection is a core VR technology that reduces motion sickness by prioritising smooth head movement over raw game performance. It has the biggest effect on game performance and there are cases where it's broken.

Legacy reprojection mode disabled

Preferred for games with low or fluctuating performance. Relies on asynchronous reprojection

• Smooth head movement even on low game performance
  
• Aggressive FPS limiting for the benefit of frame stability (only affects SteamVR 1.14) (AMD)

Legacy (interleaved) reprojection mode

Preferred for games that don't benefit from the stability of leaving it disabled

• Better game performance
  
• Large performance dips (CPU late start) extend to head movement (not specific to Linux)

Asynchronous reprojection

Preferred unless it causes performance issues (may be hardware dependent or caused by old drivers). Enabled by default

• Does not make a difference with legacy reprojection mode
  
• If VRAM is exceeded, the system isn't able to keep up, leading to extreme slowdowns
  
• Broken on newer SteamVR versions, causing artifacts or nothing at all to display (AMD), refer to Switching to an older SteamVR version
  
• Requires cap_sys_nice to be set; unsetting it essentially disables it

In order to disable it globally, refer to section Editing configuration manually. Under the "steamvr" section, set the value of this setting to false:

      "enableLinuxVulkanAsync" : false

Motion smoothing

Additional asynchronous reprojection feature

• Currently unavailable on Linux both on AMD and NVIDIA
  
• Further improves smoothness of asynchronous reprojection

Boost performance in VR

In order to avoid high latency and maximise performance, you need to adjust GPU power profile and the CPU governor.

Note: It may be beneficial to do this after launching the game (please test).

In the case of AMD GPUs, also refer to section AMD: Using alternative Vulkan drivers.

CoreCtrl[gitlab.com]

1. Launch the application and grant root access
   
2. Navigate to Global Profile
   
3. Under the GPU, set Performance mode to Fixed and select High
   
   
   
   
4. Under the CPU, set Frequency governor to Performance
   
   
   
   
5. Press Apply (top right corner)

CLI method

GPU power mode (AMD)

Run all following commands as root.

For the following steps, determine which DRM number your GPU corresponds to:

ls /sys/class/drm

Get power profile modes, look for the number corresponding to "VR":

cat /sys/class/drm/card#/device/pp_power_profile_mode

Set performance level to "manual":

echo "manual" > /sys/class/drm/card#/device/power_dpm_force_performance_level

Switch to "VR" power profile, which is "4" in this example:

echo "4" > /sys/class/drm/card#/device/pp_power_profile_mode

Reverting changes:

echo "auto" > /sys/class/drm/card#/device/power_dpm_force_performance_level

CPU governor (automatic)

Simply start SteamVR and the game with Feral GameMode:

gamemoderun %command%

CPU governor (manual)

Run the following commands as root.

Get current governor:

cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

Set it to "performance":

cpupower frequency-set --governor performance

Revert to previous governor:

cpupower frequency-set --governor <previous_governor>

Base station power management

Note: Updating base station firmware is not yet possible. If you attempt to do it, the process will end prematurely, but won't brick your base stations as of writing.

Warning: If you use VR daily, only switch them off for longer breaks, because constantly starting and stopping the motors will wear them out more quickly.

The issue of no base station power management over Bluetooth for Lighthouse v2 (Valve Index Base Station) has been fixed in the latest SteamVR versions. However, if you use older base station models, mainly use older SteamVR versions or version-hop a lot, this may come in handy.

Here is a diagram to find the optimal method:

Option A

Android
Use the Lighthouse Power Management[github.com] Android application.

Get it on F-Droid[f-droid.org] or Google Play[play.google.com].

Ubuntu Touch
Use the Lighthouse Control[gitlab.com] Ubuntu Touch application.

Get it on OpenStore[open-store.io].

Option B

Use one of these scripts (use a Bluetooth dongle if your motherboard lacks Bluetooth):

• Base Station v1: lhctrl[github.com]
  
• Base Station v2: lh2ctrl[github.com] or biechl's script[biechl.net]

Option C

You need to unplug your base stations. If your plugs lack a switch or you don't want to physically unplug them every time, smart power strips are an option.

Playing Windows games

Most games have no native Linux builds, and sometimes the Linux builds are left unmaintained. In order to use Windows game versions, use Proton.

Enable Steam Play/Proton:

1. Navigate to Steam > Settings
   
2. Go to the Compatibility tab
   
3. Enable Enable Steam Play for supported titles and Enable Steam Play for all other titles
   
   

Switch Proton version/force Linux version of games:

1. Right click the game in Steam
   
2. Select Properties...
   
3. Go to the Compatibility tab
   
4. Enable Force the use of a specific Steam Play compatibility tool
   
5. From the list, pick the Proton version to use, or Steam Linux Runtime if the game has a Linux version

In order to check what Proton version is used, on the corresponding game page, click the Info button (🛈). The compatibility settings are shown on the bottom of the section. If there's no text on the bottom of the section, the native version is used.

In order to check game compatibility, use ProtonDB[www.protondb.com], where users leave compatibility reports and instructions to fix games that don't work out of the box. It's a useful resource even for games with native Linux builds.

Editing configuration manually

Note: Use proper JSON formatting! The most significant rule is that each setting must be followed by a comma except for the last one in the section.

If SteamVR dashboard/overlay is broken for any reason, it may be necessary to edit the configuration file. On top of that, there are some settings that cannot be adjusted within the UI.

This is the main configuration file:

~/.steam/steam/config/steamvr.vrsettings

Per-app settings

Each application has an ID, which is formatted like steam.app.<AppID>, steam.overlay.<AppID>, system.generated.<Name>, openvr.component.<Name>, openvr.tool.<Name>, or a custom ID.

Finding the App ID of a Steam game:

1. Right click the game in Steam
   
2. Select Properties...
   
3. Go to the Updates tab
   
4. Make note of the "App ID" number

Some available settings with example values:

      "DominantHand" : 2
      "disableAsync" : false
      "additionalFramesToPredict" : 0
      "framesToThrottle" : 0
      "fovScale" : 100
      "motionSmoothingOverride" : 0
      "resolutionScale" : 60
      "worldScale" : 1

Global settings

Most settings should already be present in the file. However, these need to be added manually.

"steamvr" section

      "enableLinuxVulkanAsync" : false

Switching to an older SteamVR version

SteamVR is hastily updated and major issues are introduced quite frequently. Thus, it can be beneficial to use an older version.

SteamVR version comparison

• 1.14.16 / linux_v1.14 / 1600466902
  
  • Flawless asynchronous reprojection across the board (AMD)
    
  • No asynchronous reprojection support (NVIDIA) (implemented in 1.18)
    
  • Many games crash on startup if the selected Proton version is newer than 5.13, refer to section Windows games crash on SteamVR 1.14
    
  • Appears to not work on Wayland
    
  • Refer to this issue comment[github.com] to fix vrwebhelper (UI backend)
• 1.27.5 / temp_v1.27.5 / 1693508082
  
  • In-game asynchronous reprojection appears to work properly (AMD)
    
  • Anything rendered by SteamVR (overlays: dashboard, performance graph, loading screens, etc.) is not reprojected properly and causes major visual artifacts[github.com], refer to section SteamVR rendering artifacts (AMD)
• 2.0+ / public/beta
  
  • Features the new UI
    
  • Asynchronous reprojection causes nothing to be rendered, resulting in eternal darkness[github.com] (AMD)
    
  • Bad performance in per-game video settings and controller binding UI if it's done inside VR, refer to section Controller binding UI is extremely slow
• 2.6.2+ / public/beta / 1716600417
  
  • Asynchronous reprojection renders correctly (AMD)
    
  • TODO

Switching versions

• Right click SteamVR in Steam
  
• Select Properties...
  
• Go to the Betas tab
  
• Under Beta Participation, select the desired SteamVR version, which is 1.14 in this example
  
  

SteamVR stuck getting root access on first startup

On the first startup of SteamVR, there should be a window asking for root. If this fails, open your terminal and enter the following commands:

cd /path/to/SteamVR
sudo setcap CAP_SYS_NICE=eip bin/linux64/vrcompositor-launcher

Otherwise, simply replace all instances of pkexec with sudo in this file (provided that the user in /etc/sudoers has NOPASSWD set):

~/.local/share/Steam/steamapps/common/SteamVR/bin/vrstartup.sh

Launching any VR game fails

The latest versions of Steam client misbehave if SteamVR is installed and running. Namely, pressing Play fails immediately, and this shows up in Steam console (-console -dev):

LaunchApp failed with WaitingOpenVRAppQuit with "111"

The fix is simple. At least for the time being, don't use Steam to launch SteamVR, use vrstartup.sh or vrstartup-helper.sh directly instead.

Locating the script:

1. Right click SteamVR in Steam
   
2. Navigate to Manage > Browse local files
   
3. Enter the bin directory
   
4. Make a shortcut/link to vrstartup.sh or vrstartup-helper.sh for easy access, use it to launch SteamVR for the time being

Controller binding UI is extremely slow

If you find that SteamVR Controller Binding is slow and unresponsive, use it inside the browser instead. Use this URL[127.0.0.1] to access it.

SteamVR rendering artifacts

This issue appears to be directly related to reprojection. Read more here[github.com].

For newer versions, either:

• Reduce the artifacts (get rid of coloured lines) by prepending this to launch options:
  

  RADV_DEBUG=nodcc

• Disable asynchronous reprojection globally; refer to section Editing configuration manually. Under the "steamvr" section, set the value of this setting to false:
  

  "enableLinuxVulkanAsync" : false

• Reinstall SteamVR and deny root access every time
  
• Make the script smarter (bin/vrstartup.sh or bin/vrsetup.sh depending on version) by using setcap only if SteamVR 1.14 is used, which makes switching versions easier as a bonus
  

  # Replace the contents of `function SteamVRLauncherSetup()` with this
  
  if [[ "$(cat $VRBINDIR/version.txt)" == *"1600466902"* \
  	&& "$(getcap $STEAMVR_TOOLSDIR/bin/linux64/vrcompositor-launcher)" != *"cap_sys_nice"* ]] # v1.14
  then
  	pkexec setcap CAP_SYS_NICE=eip $STEAMVR_TOOLSDIR/bin/linux64/vrcompositor-launcher
  elif [[ "$(cat $VRBINDIR/version.txt)" == *"1693508082"* \
  	&& "$(getcap $STEAMVR_TOOLSDIR/bin/linux64/vrcompositor-launcher)" != *"cap_sys_nice"* ]] # v1.27.5
  then
  	pkexec setcap CAP_SYS_NICE=eip $STEAMVR_TOOLSDIR/bin/linux64/vrcompositor-launcher
  elif [[ "$(getcap $STEAMVR_TOOLSDIR/bin/linux64/vrcompositor-launcher)" == *"cap_sys_nice"* ]] # public and beta only
  then
  	pkexec setcap -r $STEAMVR_TOOLSDIR/bin/linux64/vrcompositor-launcher
  fi

Display garbled

This could happen if there are two Vulkan-capable GPUs present.

The secondary GPU may perform better with VR, however, choosing a specific GPU will not work in most games (please verify).

Fix:

1. Install Vulkan Device Chooser[github.com]
   
2. Add this to the launch options of both SteamVR and the game you want to launch:
   

   ENABLE_DEVICE_CHOOSER_LAYER=1 VULKAN_DEVICE_INDEX=<device-index> %command%

   
   Replace <device-index> with the device index of your GPU that you can find by using the following command:
   

   vulkaninfo --summary

No audio

The issue is that HMD speakers/microphone aren't automatically set as default audio input/output when SteamVR starts, since SteamVR on Linux has no audio device or volume control yet.

The solution is to make the HMD's audio input and output default audio devices.

KDE Plasma example:



If it still doesn't work:

• Get pavucontrol and launch it
  
• Go to the Configuration tab
  
• Set the profile of the sound card (graphics card) to the correct DisplayPort/HDMI output. In this example, it's HDMI 3
  
  

Note: Depending on the HMD, inputs/outputs may only be connected if SteamVR is running.

If you would prefer to quickly switch by running a short command instead, add this script to any path in $PATH:

#!/bin/bash

# asw.sh - audio switcher
# Usage: `asw h` for headset, `asw i` for Index

# Find sink and source names by running:
# pw-cli list-objects Node

if [[ $1 = 'h' ]] # Headset or speakers
then
	pactl set-default-sink "alsa_output.pci-XXXX_XX_XX.X.analog-stereo"
	pactl set-default-source "alsa_input.pci-XXXX_XX_XX.X.analog-stereo"
elif [[ $1 = 'i' ]] # Index
then
	pactl set-default-sink "alsa_output.pci-XXXX_XX_XX.X.hdmi-stereo-extra4"
	pactl set-default-source "alsa_input.usb-Valve_Corporation_Valve_VR_Radio___HMD_Mic_XXXXXXXXXX-LYM-01.mono-fallback"
else
        echo "\`asw h\` for headset, \`asw i\` for Index"
fi

You need to replace your device IDs according to sink/source IDs, and then you can run the script by using asw h for headset/speakers or asw i for the Index.

No microphone input

The issue was observed on Valve Index, it may affect other HMDs as well.

If you use PulseAudio, set the default sample rate to 48 kHz:

1. Edit this file:
   

   ~/.config/pulse/daemon.conf

2. Append this line:
   

   default-sample-rate = 48000

3. Restart PulseAudio:
   

   pulseaudio -k

If that is not enough, edit udev rules according to this page[github.com].

If it still does not work, refer to section No audio.

Windows games crash on SteamVR 1.14

If Proton >5.13 is selected, some Windows games, particularly Unity OpenVR games will crash[github.com]:



Select Proton 5.13 for each misbehaving Windows game you want to play with this SteamVR version.

Issues not specific to Linux experience

This section is dedicated to hardware or software issues that aren't specific to the Linux experience and haven't been mentioned elsewhere in the guide.

Inconsistent connection over HDMI

If your headset connects via HDMI, you need to ensure that the cable is compatible with the headset.

If you find that issues only started arising after using the current cable, try getting a genuine replacement cable. In the case of HTC Vive, here is a table of cables that were confirmed to work.

Extreme slowdown with Legacy Reprojection Mode disabled

Check VRAM usage. If it is close to 100%, reduce in-game settings like texture resolution and/or drop screen resolution.

Just like the game, asynchronous reprojection requires VRAM to operate, and if it can't have enough, everything will chug. A lot.

Known issues without a solution

• Valve Index cameras don't work in SteamVR, even though other software can access it like any webcam

Related guides

VR on Linux guide[gitlab.com]: long and descriptive guide with many game-specific entries; Steam mirror:
https://steamcommunity.com/sharedfiles/filedetails/?id=2984005943

Beat Saber mods
https://steamcommunity.com/sharedfiles/filedetails/?id=2337011257

VRChat tweaks
https://steamcommunity.com/sharedfiles/filedetails/?id=2670484864

Half-Life: Alyx Workshop Tools
https://steamcommunity.com/sharedfiles/filedetails/?id=2103751103

Boneworks on Linux[blog.lightwo.net] (brief overview of issues already addressed in this guide)

Credits

• Guide editors
  
• gibarel1
  
• sit_up_straight
  
• plz uninstall (*￣m￣)
  
• RamsomOfThulcandra
  
• KCGD_r
  
• k0lor

[lightwo]

Sorry about the confusing comment, let me clarify.

This was regarding Vive Pro (1/2):
I believe Vive Pros do work, but I can't vouch for either as the unofficial compatibility list on top is based on comments under this guide, mostly.

This was regarding PSVR2:
(...) but as it's not a SteamVR-native headset, if anything, it may be compatible under Monado, which develops somewhat slowly.

I suck at writing and I constantly have to edit the shit I post, sorry.

[lightwo]

I believe Vive Pros do work, but I can't vouch for either as the unofficial compatibility list on top is based on comments under this guide, mostly. You'll have to find the information on your own, but as it's not a SteamVR-native headset, if anything, it may be compatible under Monado, which develops somewhat slowly.

Being real, the whole guide is somewhat abandoned at this time anyway... but it should at least reduce the amount of time wasted on confusing Internet searching.

[tyl0413]

I wish PSVR2 worked, especially after it got a price cut too. I'm only interested in standalone and below 1K, shame the whole market is moving towards standalone facebook tier crap.
The the currently available HTC headsets work atleast such as Vive Pro 2 and Vive Cosmos?

[MildConcernAtTheDisco]

Only way I've gotten it to work was through Flatpak and even then it was iffy. A few games run, but most will still try to run in the monitor or will crash/freeze completely. I'm using a Vive Pro on Kubuntu 24.04.

[Sabasti]

You may want to add, that if controllers are refusing to pair (especially since SteamVR appears to not load the settings panel or pairing panel properly) is to reset the controllers (particularly for HTC Vive). This can be done by pressing every single button and holding until the tone sounds.

Light should change from blue to green accordingly and hopefully automatically pair.

If not go to lighthouse_console (seamapps/steamvr/tools/lighthouse_console) type 'unpairall' and try again. This might need testing by someone with a wireless headset as the headset may also need to be reset.

[Entity325]

IT WORKS, MARTY!

So my best guess is that SteamVR caches a few bits of headset information when you first fire it up, and because I had changed both GPU and distro since that info was cached, whatever it had stored was messed up. Deleting the ENTIRE Steam folder in my /home directory, and then installing Steam and SteamVR from scratch seems to have remedied the issue.

[mycatismycat]

does the meta quest support steamvr

[Neumond]

Very good guide! Huge thanks!

[soup.dev]

does ALVR let you use quest wired (with a link cable) or is it only airlink?

[DUMFAYCE !!]

does anyone know how to fix vive touchpads stuck in scrolling mode