Linux User's Guide to Beat Saber Mods

Quick and easy guide for getting mods set up on Linux!

Why mod?

Modding allows you to get a lot more customization, control and even content out of your game. There are mods for improving the camera, removing visual clutter, adding extra functionality to custom levels, quality-of-life fixes, and more. Most mods have little to no performance impact so there's no reason not to check them out!

Image: Custom level Midnight Lady[beatsaver.com] running with Noodle Extensions and Custom Sabers

Method 1: Using BSManager

BSManager[www.bsmanager.io] is a tool used to manage game versions, mods, maps and more. It is currently the most streamlined method of modding Beat Saber. In this guide, I will only covering everything you need to get the game up and running. If at any point you feel you need a deeper explanation on something in BSManager, they have a very well-documented wiki I recommend checking out.[github.com] I will be referencing it throughout this guide.

BSManager requires a Steam/Oculus login to verify game ownership. While the code for the launcher is public and generally considered safe to use, if this is something that makes you uncomfortable then I would recommend following Method 2 for a more manual install.

BSManager has a variety of methods for installation.[github.com] In this guide, we will be using the Flatpak, as it's the most likely to work for your distribution.

Prerequisites:

• Flathub[flathub.org] repo configured for Flatpak.
  
• Proton installed through Steam.

Installing and Using BSManager:

1. Download the latest .flatpak release[github.com] and install it with:

   flatpak install --user <FILE PATH>

2. Run the application from your app launcher.
   
3. When asked for the path to the Proton folder:
   For the Steam distro-native package (deb, rpm, etc.):
   

   ~/.local/share/Steam/steamapps/common/Proton <version>/

   For the Steam Flatpak:
   

   ~/.var/app/com.valvesoftware.Steam/.steam/steam/ubuntu12_32/steamapps/common/Proton <version>/

4. Download a version of the game. The version labeled "Recommended" will have the most mod support.
   
5. When asked, login with Steam or Oculus.[github.com] *Not currently supported
   
6. Select the downloaded version and move over to the "Mods" tab. Select the mods you would like to install.
   
7. Launch the game from the launcher and enjoy a modded Beat Saber!

You can add additional mods at any time using this tool. You will also be notified when an update is available to an already installed mod.

Method 2: Using BeatSaberModManager

BeatSaberModManager[github.com] is a graphical mod installer for Linux. It is a more manual approach to installing Beat Saber mods on Linux and keeping them updated.

To use BeatSaberModManager:

1. Make sure you have launched Beat Saber in VR at least once.
   
2. Download the latest release of BeatSaberModManager (click)[github.com]
   
3. Extract the zip and run the executable (you may need to mark it as executable through right click > Properties)
   
4. Right-click on the game in your Steam library, go to Properties > Local Files > Browse...
   
5. Copy the path of the directory and paste it where prompted in BeatSaberModManager.
   
6. Ensure BeatSaberModManager is set to the correct, latest version of Beat Saber.
   
7. Check each mod you want and install.

This process can be repeated at any time to add additional mods or to update your current ones.

Installing Mods Not Listed in the Mod Manager

Both mod managers will be able to install the most popular/core mods, but there are still other mods available for use from places like the Beat Saber Modding Group.[discord.gg]

To install these mods:

1. Make sure you have downloaded and used either BSManager or BeatSaberModManager (or have installed BSIPA).
   
2. Download the mod's DLL file.

If using BSManager:

1. Select the version you're using.
   
2. Drag and drop the mod DLL into the window.

OR

1. Click on the version options button at the top-right corner, then select "Open Folder."
   
2. Navigate to your Plugins folder and copy-paste the DLL.

If using BeatSaberModManager:

1. Right-click on the game in your Steam library, go to Properties > Local Files > Browse...
   
2. Navigate to your Plugins folder and copy-paste the DLL.

Extra notes:

• Read the mod's description! Some mods require certain dependencies to work properly, so make sure you read the mod's description in order to make sure it works properly.

Notes on Mod Breakage

Mod functionality is not guaranteed! While I personally have not run into any issues, keep in mind that most mods are not tested for use on Linux.

Game updates will break mods! Most patches will cause mods to stop working. This is at no fault of the game's developers, as mods are not officially supported. If you use BSManager, this isn't a concern, since it will keep using the version of the game you installed and not update to a new one until you decide to.

If you are not using BSManager, you may be interested in other methods of preventing the game from updating or downgrading to an older version with mod compatibility.

Regardless of what you use to install mods, you should always check every so often for new updates to ensure the best stability and feature set.

Installing Custom Songs

There are several different options for installing Custom Songs.

BSManager:

1. Select the version you would like to use.
   
2. Move to the "Maps" tab to browse your installed songs and to download new ones.

In-Game:

1. Install the BeatSaverDownloader mod.
   
2. Go to the game's main menu.
   
3. Look left to the "mods" panel and click "More songs".
   
4. Search for the song you want and click Download!

Manually:

1. Download the song's ZIP file.
   
2. Right-click on the game in your Steam library, go to Properties > Local Files > Browse...
   
3. Navigate to Beat Saber_Data > CustomLevels
   
4. Extract the custom song's folder into the CustomLevels directory.

Extra notes:

• Some songs require extra mods! Most commonly these are Chroma, Mapping Extensions and/or Noodle Extensions. If you can't load a song, you can check what mods it needs by selecting the "?" in the top right of its panel.
  
• Some great sites for finding songs are BeatSaver[beatsaver.com] and BeastSaber.[bsaber.com] BeatSaver offers a more robust search while BeastSaber has Curator Recommended songs that are great for finding something new.

Conclusion

I hope this guide was able to help you. If it did, a rating would be very appreciated! If you have any questions:

• Consult the BSManager[github.com] or BeatSaberModManager[github.com] documentation.
  
• Browse the BSMG Wiki[bsmg.wiki]
  
• Ask the users of the BSManager Discord[discord.gg] or the Beat Saber Modding Group[discord.gg]
  
• Leave a comment on this guide, myself and others will be able to help you.

Special Thanks

BSManager contributors[github.com] - For maintaining the BSManager Linux port!
affederaffe[github.com] - for developing BeatSaberModManager and keeping it updated!
muffn[muffnlabs.de] - for his beautiful MS Paint art!
You - for reading my guide!

[Silent]

Hi V, yep it should, although thats the build that I rarely test. You could ping me in the BSM discord so I can help you out and resolve any flatpak issues.

[󠁳⁧⁧󠁳v]

Hi Silent, is Flatpak Steam officially(ish) supported? I can play Beat Saber (unmodded) from Flatpak Steam, but launching from BSManager Flatpak just shows a black window open and close.

Looking at the logs there are a few errors, first being `Error while checking if Steam is running as admin Error: Unable to build process from pid: File not found: /proc/112423`

[Maria D.B.]

Added!

[Silent]

Linux support in BSManager is in the main release 1.5.0. If you have any question or any issues encountered, feel free to ask since I'm one of the main linux maintainer there.

[Maria D.B.]

Sweet! I'll keep an eye on it and add it once it's in the main release.

[Silent]

You could also mod Beat Saber with BSManager with the latest alpha release. I've added the documentation within both BSManager [github.com] and BSMG [bsmg.wiki] (the PR isn't merged yet)

[Maria D.B.]

Added, thank you

[yao mtc]

Thanks for the guide, I'll try it out. Also I would suggest mentioning something about keeping/installing a previous version of the game when an update releases and inevitably breaks mods

[clav]

https://github.com/affederaffe/BeatSaberModManager/
this should be used instead of beatroni

[Maria D.B.]

SaberFactory is used for custom sabers as of writing. Last time I checked it wasn't in any mod managers yet so you'll likely have to install it into your Plugins folder manually.
https://github.com/ToniMacaroni/SaberFactory/releases
Hope this helps