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.
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
- Valve Index
- Other (less reliable support):
- Oculus Quest
- Oculus Quest 2
- Oculus Rift DK
- Oculus Rift CV
- Oculus Rift S
- PICO 4
- Oculus Quest
HMDs that are not listed may not necessarily be incompatible, please comment if you get your model to work. - SteamVR-native (least software required):
Basic setup
For SteamVR-native HMDs, this will be sufficient. For other devices, refer to sections Wireless HMDs and Other VR/XR hardware.
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.
- Use Steam to install SteamVR and start it with your HMD connected
- Follow the on-screen instructions
- 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:
* Potential solution:
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:
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
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.
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
- AMDVLK
- AMDGPU-PRO
Instructions
- 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]
- 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
- 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
- AMDVLK:
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.
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
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
Additional asynchronous reprojection feature
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.
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:
Get current governor:
Set it to "performance":
Revert to previous 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]
- Launch the application and grant root access
- Navigate to Global Profile
- Under the GPU, set Performance mode to Fixed and select High
- Under the CPU, set Frequency governor to Performance
- 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:
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].
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
AndroidUse 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:
Switch Proton version/force Linux version of games:
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.
Enable Steam Play/Proton:
- Navigate to Steam > Settings
- Go to the Compatibility tab
- Enable Enable Steam Play for supported titles and Enable Steam Play for all other titles
Switch Proton version/force Linux version of games:
- Right click the game in Steam
- Select Properties...
- Go to the Compatibility tab
- Enable Force the use of a specific Steam Play compatibility tool
- 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:
Finding the App ID of a Steam game:
Some available settings with example values:
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:
- Right click the game in Steam
- Select Properties...
- Go to the Updates tab
- 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)
- Flawless asynchronous reprojection across the board (AMD)
- 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)
- In-game asynchronous reprojection appears to work properly (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
- Features the new UI
- 2.6.2+ / public/beta / 1716600417
Switching versions
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:
Otherwise, simply replace all instances of pkexec with sudo in this file (provided that the user in /etc/sudoers has NOPASSWD set):
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):
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:
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:
- Right click SteamVR in Steam
- Navigate to Manage > Browse local files
- Enter the bin directory
- 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:
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:
The secondary GPU may perform better with VR, however, choosing a specific GPU will not work in most games (please verify).
Fix:
- Install Vulkan Device Chooser[github.com]
- 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:
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 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:
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 you use PulseAudio, set the default sample rate to 48 kHz:
- Edit this file:
~/.config/pulse/daemon.conf - Append this line:
default-sample-rate = 48000 - 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.
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.
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.
Just like the game, asynchronous reprojection requires VRAM to operate, and if it can't have enough, everything will chug. A lot.
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)
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
Comments
There are no comments yet.