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.

• 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.

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.

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

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.

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.

• 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

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.

• 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
    

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 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.

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)

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)

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:

Additional asynchronous reprojection feature

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

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.

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)

Run all following commands as root.

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

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

Set performance level to "manual":

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

Reverting changes:

Simply start SteamVR and the game with Feral GameMode:

Run the following commands as root.

Get current governor:

Set it to "performance":

Revert to previous governor:

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:



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].

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]

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.

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.

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:

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:

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

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

• 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

• 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
  
  

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:

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

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):

The fix is simple. At least for the time being, don't use Steam to launch SteamVR, use vrstartup.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 for easy access, use it to launch SteamVR for the time being

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.

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

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

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:

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.

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.

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.

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.

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.

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.

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

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)

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