Installing the game on Linux

Easy installation options

If you do not wish to perform a manual install, here are the official Flatpak packages (for Fedora, Linux Mint, Manjaro, PopOS!, Red Hat, CentOS, elementary OS, SteamOS etc.):

• Stable release:
  flatpak --user install https://flatpak.vintagestory.at/VintageStory.flatpakref
• Unstable release:
  This build is intended for testing upcoming changes before they are released as stable. Expect more bugs and issues compared to the stable version.
  flatpak --user install https://flatpak.vintagestory.at/VintageStoryUnstable.flatpakref

You can also add the remote once and install it from your App Center or Software app:
flatpak --user remote-add --if-not-exists vintagestory https://flatpak.vintagestory.at/VintageStory.flatpakrepo

When adding the remote and installing the flatpak through the App Center or Software app make sure that below the Install button the vintagestory remote is selected.
These packages are maintained directly by Anego Studios. They are updated more quickly than Flathub and also include an unstable version.

The Flathub Flatpak package is also maintained by Anego Studios but it may lag a bit behind (a few hours or a day) compared to the package we provide via flatpak.vintagestory.at.

  If not already installed, you can install Flatpak itself as well.

• Community-maintained packages:
  • An AUR package (for Arch Linux)
  • A NixOS package (for NixOS 24.11+)

If you install the game using any of these methods, you can start it by clicking the Vintage Story menu entry in your desktop environment's application launcher.

Disclaimer: Community packages above are maintained by volunteers to the open-source community. Anego Studios can't be held responsible if they don't work as intended or don't work at all. In addition, the game itself may not always be up to date with the latest stable version that's released officially.

Manual installation

The Vintage Story game client relies on three main components: the .NET Runtime, OpenAL, and OpenGL.

To perform a manual installation, you are expected to know how to open a terminal, what package manager your Linux distribution uses, and how to use your package manager's search, list, and install commands or command flags.

Some common package managers (apt, dnf, yum, and apk) share a similar command format, so the following apt examples can be used by substituting apt with a near-equivalent command. Other package managers may stray slightly from the above four or use a completely different format, as is the case with pacman in Arch.

Installing .NET

Vintage Story requires the .NET Runtime to run.

• Versions 1.21.0 and newer require .NET 8
• Versions 1.20.x to 1.18.8 require .NET 7
• Versions 1.18.7 and older require .NET Framework 4 / Mono

Note: If you install the game using the Flatpak version, you do not need to install .NET manually. The runtime is bundled inside the Flatpak package.

The easiest way to install the .NET Runtime on your Linux system is to use a package available in your distribution's official package repository (see below).
If your distribution no longer has the required version in its repositories, install it manually using .NET manually.

Install .NET via package manager

Find the package name

Package names for some popular distributions are as follows:

A screenshot of the process of searching for and installing the .NET 7 Runtime in Ubuntu with apt. The commands used and desired search results are highlighted.

• .NET 8 (Vintage Story 1.21.0+)
  • Alpine Linux (v3.20+): dotnet8-runtime
  • Arch Linux: dotnet-runtime-8.0
  • Fedora: dotnet-runtime-8.0
  • Linux Mint: dotnet-runtime-8.0
  • Ubuntu (24.04+): dotnet-runtime-8.0

• .NET 7 (Vintage Story ≤ 1.20.x)
  • Alpine Linux (until v3.19): dotnet7-runtime
  • Arch Linux: dotnet-runtime-7.0
  • Fedora (until Fedora 36): dotnet-runtime-7.0
  • Linux Mint: dotnet-runtime-7.0
  • Ubuntu (until 22.04): dotnet-runtime-7.0

If your distribution isn't listed or if you want to check whether the package is installed, you can search for dotnet.*runtime or dotnet runtime in your package manager and copy the name for version 8 into an install command (see example below).

As an example, these are two ways to search for the .NET Runtime with apt (in Ubuntu); the example using grep is slower but provides a cleaner output:
Search with Grep: sudo apt list | grep -E dotnet.*runtime
Normal Search: sudo apt search dotnet.*runtime

Install the package

Once you have identified the correct package name, install it with your package manager. For example, on Ubuntu:

• For 1.21.0+: sudo apt install dotnet-runtime-8.0
• For ≤ 1.20.x: sudo apt install dotnet-runtime-7.0

If it is already installed, the search list entry will have some text indicating so near the beginning or end of the line, usually [Installed].

For advanced users:
Microsoft also offers official package repositories for several Linux distributions and guides for manual or scripted installations as alternatives. An overview of these options is available on dotnet's GitHub.

Installing .NET manually

You can install .NET 8 using the scripted installer or by performing a completely manual installation. Detailed instructions for both methods are available here:

• Manual Installation (for advanced users)
• Scripted Installation (recommended, see below)
  

For the scripted Installation, execute the following commands as default user:
Note: Execute the commands in code-blocks in a terminal of your choice

1. wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh
   <(Downloads the install script)
2. chmod +x ./dotnet-install.sh
   (Makes the install script executable)
3. ./dotnet-install.sh --channel 8.0
   (Execute the install script and install .NET 8)

Now you need to set an environment variable to let your system know where .NET 8 is installed. To set the environment variables system-wide you will need to add them to your shell:

1. In your terminal, execute this command to find out which shell you use:
   echo $SHELL
2. Now open one of the files corresponding to your shell (you can use any editor you like):
   bash: nano ~/.bash_profile or nano ~/.bashrc
   zsh: nano ~/.zshrc or nano ~/.zprofile
   If it is neither of these two, search for the relevant files online (e.g. "set environment variables fish")
3. Add the following two lines at the end of the file and save it (in nano, saving can be done by pressing STRG+X then Y then ENTER):
   export DOTNET_ROOT=$HOME/.dotnet
export PATH=$PATH:$DOTNET_ROOT:$DOTNET_ROOT/tools
4. Make sure you save your file by pressing Ctrl+X then pressing Y then pressing Enter (Or however you do it with your editor if you used something other than nano)
5. Logout & Login or restart your PC (Just running exec bash or exec zsh to restart the shell may also be sufficient)
6. To check if it worked, open a terminal and execute echo $DOTNET_ROOT; if the output is /home/YOURUSERNAME/.dotnet it worked!

Note:

• Versions 1.21.0 and newer require .NET 8
• Versions 1.20.x to 1.18.8 require .NET 7
• Versions 1.18.7 and older require .NET Framework 4 / Mono

Installing OpenAL

Recent versions of the game (since the update to .NET 7) include the library, so this section may be skipped.
OpenAL is a cross-platform audio library, needed to play game sounds in Vintage Story. Even with older versions however, OpenAL may already be installed, either by default as part of another game's or application's installation.

If you don't have it already, the OpenAL library should be present in your distribution's package repository. Search for openal, libopenal, libopenal-dev or anything that provides the required libopenal.so library.

As an example, searching for and installing OpenAL with apt might be done with these commands (in Ubuntu); prefer the grep variant here as there are many more extraneous results:
Search: sudo apt list | grep openal OR sudo apt search openal
Install: sudo apt install libopenal-dev

Installing Graphics Drivers

OpenGL is the 3D graphics library the game uses, which needs to be supported by a graphics driver. If you have a graphics card (integrated or dedicated) but do not have drivers installed, you will need to search online for installation instructions for your specific hardware, Linux distribution, and package manager. The process will be similar to the installation of .NET above, but may include additional steps to add third-party repositories to your package manager.

NVIDIA graphics cards can make use of nvidia driver packages, while Intel and AMD graphics will need to use mesa driver packages. You can use the following command to check if parts of the mesa or nvidia packages are installed (in Ubuntu):
Search Installed: sudo apt list --installed | grep -E "mesa|nvidia"

Launching the game

Once you have its dependencies installed, you're ready to download and run the game.

Sign in and find the client download for Linux in the Vintage Story website's client area. The Linux download is a tarball (.tar.gz archive) that will need to be extracted. Most desktop environments will allow you to right click the archive and extract it from the context menu, or double-click it to open an archive viewer with an "Extract" option.

If neither option is available, right click in empty space next to the archive to open a terminal in (or use the cd command to set the terminal's directory to) the directory containing the archive, then use the tar command to extract the contents of the archive:
Change Directory: cd /home/myusername/Downloads
Extract Archive: tar -xvf ./vintagestory_tarball.tar.gz

Be aware that path and file names are case-sensitive, but you can press TAB while typing to auto-complete them. Make sure to substitute the directory in the cd command and archive name in the tar command with the location and filename of your download.

Once the vintagestory directory has been fully extracted, you can enter it and double-click to execute the run.sh or Vintagestory files, or open a terminal in that directory (using the same process as above) and run one of them from the command line:
Run the Game: ./run.sh OR ./Vintagestory

The game files also contain a script, install.sh that is intended to install the game in ~/.local/share/vintagestory/ (prior to 1.19.2 ~/ApplicationData/vintagestory/) and create a shortcut on your desktop as well as add support for moddb 1 click install and connect via URL (vintagestoryjoin://ip:port). This install script may not work for everyone, so you may need to take these steps manually or create the target install folder before running the script (there may be a permissions issue?). For more details please refer to the Forum thread linked below.

Dedicated or integrated GPU

If your Linux system has two GPUs available - common where many modern CPUs have an integrated GPU - then you may need to help the runtime select the correct GPU to play the game, normally you'll want that to be the dedicated GPU. There is a commented out line in `run.sh`: # export DRI_PRIME=1. If your system is not already using the correct GPU, you can remove the # from that line to try to force your system to use GPU 1. Commonly the dedicated GPU will be GPU 1. But sometimes the dedicated GPU might actually be GPU 0, so if DRI_PRIME=1 does not seem to be working you can also perhaps try DRI_PRIME=0 there.

You can see which of your GPUs the game is using, either in-game in the Ctrl+F3 debug screen, top left, or else in the client-main.log file lines 9-12.

Updating the game

To update the game you can run the install.sh found in the update download from any location, it will move the old installation to a backup location and after that move the new files to the default installation directory and reinstall the desktop entries. At the end, it will ask you if you want to delete the old installation files.

You can also update the game by extracting game binary files from the tar.gz downloaded from vintagestory.at. That should work fine, except that it is a good idea to extract those files into an empty folder where possible. If that is not possible for some reason, then we strongly recommend that you at least delete the /assets/ folder from your previous Vintage Story installation. If you simply extract the archive into an existing game installation folder without deleting /assets/, some previous asset files will remain, leading to minor issues - e.g. unintended blocks or items in the game, duplicated guides in the Handbook Guides tab.

(To make things more complicated, some of the downloads with sizes around 50MB contain all the game files except for music. In that case, you shouldn't delete the whole of the /assets/ folder because you would lose the music you already have: instead delete everything in /assets/ except for the subfolders /assets/game/music and /assets/survival/music - keep those subfolders.)

If you use a package manager, that may take care of some of this for you.

Troubleshooting

If you have any issues, the Forum thread on working linux setups might help you considerably. Please do share your own experiences there. You might also want to use the mesa_glthread optimization, which works well for some players.

GL threading issues

However, many users have reported problems with the game with OpenGL threading enabled.

OpenGL threading optimization is enabled by default in some configurations and can lead to the following problems:

• Mouse cursor not registering clicks properly
• Inability to resize the game window
• Hanging, freezing, etc.

To disable OpenGL threading, you will need to create a mesa_glthread environment variable and set it to false. You can easily test it, by launching the command line, navigating to the directory where Vintage Story resides and running the mesa_glthread=false ./Vintagestory command. If you don't want to use the command, look up how to make Linux environment variables permanent and restart the system.

If you installed the game using Flatpak instead, try launching it with the command: flatpak run --env=mesa_glthread=false at.vintagestory.VintageStory vintagestory. You can make it permanent by typing: flatpak override --env=mesa_glthread=false at.vintagestory.VintageStory

sudo for first time run

Some players have reported needing to run sudo ./Vintagestory to launch the game the first time: this may depend on how it was installed.

Graphical glitches

Some people report minor graphical issues which are platform and driver dependent. Vintage Story makes use of a large variety of GLSL shaders for its rendering effects including commonplace elements such as grass and leaf colors in different climates. Bugs in the GPU driver's implementation of GLSL may cause artifacts with some of these. There's a chance a driver update might improve the situation. The in-game Graphics settings give high level control over many of the effects, you can try different settings.

Text font

The text fonts are configurable in clientsettings.json with default values:

   "defaultFontName": "sans-serif",
   "decorativeFontName": "Lora",

This leaves it to the operating system to select the best sans-serif font. Some users have reported that italic text (including the quote on the main menu page) looks better if font "Noto Sans" is specified as the defaultFontName.

Dotnet issues on NixOS 24.11

Some people report receiving a NixOS warning saying dotnet-runtime-7.0.20 is insecure. This can be corrected by adding the following to /etc/nixos/configuration.nix:

    nixpkgs.config.permittedInsecurePackages = [
	"dotnet-runtime-wrapped-7.0.20"
	"dotnet-runtime-7.0.20"
    ];

and then running nixos-rebuild switch.

Video Walkthrough

Manual installation walkthrough.