Installation

Installation Overview

This guide covers detailed installation steps for Xenia on both Windows and Linux platforms. Choose your platform below to get started.

Windows Installation

Full support with Visual Studio 2022

Linux Installation

Experimental support with Clang 19+

System Requirements

Minimum Requirements

Processor: 64-bit x86_64 CPU with AVX support
Memory: 4GB RAM
Graphics: GPU with Vulkan 1.1 or Direct3D 12 support
Storage: 500MB for Xenia + game-dependent storage
Operating System: Windows 10/11 or modern Linux distribution

Recommended Requirements

Processor: Modern Intel Core i5/AMD Ryzen 5 or better
Memory: 8GB RAM or more
Graphics: NVIDIA GTX 1060 / AMD RX 580 or better with latest drivers
Storage: SSD with 20GB+ free space
Operating System: Windows 11 or Ubuntu 22.04+

A 64-bit system is required - Xenia cannot run on 32-bit systems.

Windows Installation

Option 1: Download Pre-Built Binary (Recommended)

Download Xenia

Choose a Xenia variant based on your needs:

Xenia Canary (Recommended)
Xenia Master
Xenia Mousehook Fork

Xenia Canary is the most actively maintained fork with the latest features and fixes.

Visit xenia-canary releases
Download xenia_canary.zip
Extract to your desired location (e.g., C:\Xenia\)

Xenia Canary includes improvements like better compatibility, performance optimizations, and additional features.

Xenia Master is the original branch (less frequently updated).

Visit xenia-project releases
Download xenia_master.zip
Extract to your desired location

Install Prerequisites

Visual C++ Redistributables

Xenia requires Visual C++ Redistributables to run:

Download Visual C++ Redistributable 2022
Run the installer
Restart your computer if prompted

Graphics Drivers

Ensure you have the latest GPU drivers:

NVIDIA: GeForce Drivers
AMD: Radeon Drivers
Intel: Arc/Iris Drivers

Configure Windows Defender (Optional)

Some users report Windows Defender impacting performance:

Open Windows Security → Virus & threat protection
Click Manage settings under “Virus & threat protection settings”
Click Add or remove exclusions
Add the Xenia folder as an exclusion

Only exclude folders you trust. Only download Xenia from official sources.

First Run

Navigate to your Xenia folder
Double-click xenia_canary.exe or xenia_canary.exe
Xenia will create configuration files on first launch
The main window should appear

If you see an error about missing DLLs, ensure you’ve installed the Visual C++ Redistributables.

Option 2: Build from Source

For developers or those who want the latest changes:

Install Build Tools

Install the required development tools:

Visual Studio 2022 (Community Edition or higher)
- Download from visualstudio.com
- During installation, select:
  - “Desktop development with C++”
  - “C++ CMake tools for Windows”
  - “Windows 11 SDK (10.0.22000.0 or newer)”
Python 3.9 or later (64-bit)
- Download from python.org
- Important: Check “Add Python to PATH” during installation
Git for Windows
- Download from git-scm.com

Clone Repository

Open Command Prompt or PowerShell:

# Clone Xenia Canary (recommended)
git clone https://github.com/xenia-canary/xenia-canary.git
cd xenia-canary

# Or clone original Xenia
# git clone https://github.com/xenia-project/xenia.git
# cd xenia

Run Build Setup

Initialize the build environment:

xb setup

This command will:

Update git submodules
Configure the build environment
Run premake to generate project files

Build Xenia

Build using the xb script:

xb build

The built executable will be in:

Debug: build/bin/Windows/Debug/xenia_canary.exe
Release: build/bin/Windows/Release/xenia_canary.exe

Use Release builds for playing games. Debug builds are significantly slower and meant for development.

Linux Installation

Linux support is extremely experimental and presently incomplete. Many features may not work correctly. Expect issues with audio, input, and game compatibility.

Prerequisites

Install System Dependencies

Install required packages for your distribution:

sudo apt-get update
sudo apt-get install -y \
  build-essential \
  clang-19 \
  llvm-19 \
  libc++-dev \
  libc++abi-dev \
  libgtk-3-dev \
  liblz4-dev \
  libsdl2-dev \
  libvulkan-dev \
  libx11-xcb-dev \
  mesa-vulkan-drivers \
  ninja-build \
  python3 \
  git

Install Vulkan Drivers

Ensure you have proper Vulkan support for your GPU:

NVIDIA
AMD
Intel

# Install proprietary NVIDIA drivers
sudo apt-get install nvidia-driver-XXX  # Replace XXX with version

# Verify Vulkan
vulkaninfo | grep "GPU"

# Mesa drivers (usually pre-installed)
sudo apt-get install mesa-vulkan-drivers vulkan-tools

# Verify Vulkan
vulkaninfo | grep "GPU"

# Intel Vulkan drivers
sudo apt-get install mesa-vulkan-drivers intel-media-va-driver vulkan-tools

# Verify Vulkan
vulkaninfo | grep "GPU"

If vulkaninfo doesn’t work, install it with: sudo apt-get install vulkan-tools

Set Compiler Environment

Configure the build to use Clang 19:

export CC=clang-19
export CXX=clang++-19

# Add to ~/.bashrc for persistence:
echo 'export CC=clang-19' >> ~/.bashrc
echo 'export CXX=clang++-19' >> ~/.bashrc

Building Xenia

Clone Repository

# Clone Xenia Canary
git clone https://github.com/xenia-canary/xenia-canary.git
cd xenia-canary

# Or clone original Xenia (less Linux support)
# git clone https://github.com/xenia-project/xenia.git
# cd xenia

Setup Build Environment

# Make xb script executable
chmod +x xb

# Run setup
./xb setup

This will:

Initialize git submodules
Configure the build system
Generate build files with CMake

Build Xenia

# Build debug version
./xb build

# Or build release version (recommended for playing games)
./xb build --config=release

The build process may take 10-30 minutes depending on your system.Built binaries will be in:

Debug: build/bin/Linux/Debug/xenia
Release: build/bin/Linux/Release/xenia

Run Xenia

# Run the built executable
./build/bin/Linux/Release/xenia

# Or with a game:
./build/bin/Linux/Release/xenia /path/to/game.xex

Create a symlink for easier access:

sudo ln -s $(pwd)/build/bin/Linux/Release/xenia /usr/local/bin/xenia

Linux Troubleshooting

Clang 19 not found

If Clang 19 isn’t available in your distribution’s repositories:

# Add LLVM repository (Ubuntu/Debian)
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 19

Vulkan not working

Verify Vulkan is properly installed:

# Check for Vulkan devices
vulkaninfo --summary

# Check ICD loader
ls /usr/share/vulkan/icd.d/

# Test Vulkan
vkcube

If vkcube doesn’t work, Xenia won’t work either. Fix your Vulkan installation first.

Build fails with libc++ errors

Ensure libc++ is properly installed:

sudo apt-get install --reinstall libc++-dev libc++abi-dev

Or try building with libstdc++ instead (not officially supported):

# Edit build files to use libstdc++ - not recommended

GTK errors on launch

Install GTK3 development files:

sudo apt-get install libgtk-3-dev

Post-Installation Setup

Directory Structure

After first launch, Xenia creates this directory structure:

xenia/
├── xenia_canary.exe (or xenia)
├── xenia-canary.config.toml          # Main configuration file
├── content/                   # Save data and profiles
│   ├── 00000001/              # Profile data
│   └── [GAME_TITLE_IDs]/      # Per-game save data
├── cache/                     # Shader cache
└── portable.txt               # Makes Xenia portable (optional)

Configuration File

The xenia-canary.config.toml file is created on first launch. Edit it to customize Xenia’s behavior:

# Graphics Configuration
[GPU]
gpu = "vulkan"          # Options: vulkan, d3d12 (Windows only), null
vsync = true            # Enable V-sync

# CPU Configuration  
[CPU]
break_on_unimplemented_instructions = false

# Audio Configuration
[APU]
apu = "xaudio2"         # Windows: xaudio2, Linux: sdl

# Storage Paths
[Storage]
content_root = "content"   # Save data location
cache_root = "cache"       # Shader cache location

See the Configuration Reference for all available options.

Making Xenia Portable

To make Xenia store all files in its own directory:

Create an empty file named portable.txt in the Xenia directory
All configuration and save data will be stored relative to the executable

# Windows
type nul > portable.txt

# Linux
touch portable.txt

Updating Xenia

Pre-Built Binaries

Backup Your Data

Before updating, backup your:

content/ folder (save data)
xenia-canary.config.toml (settings)

Download New Version

Download the latest release from the same source you originally used.

Replace Executable

Replace the old xenia_canary.exe with the new one. Keep your content/ and config files.

Source Builds

# Pull latest changes
git pull

# Update submodules
./xb pull

# Rebuild
./xb build --config=release

The xb pull command automatically updates submodules, rebases your changes, and runs premake.

Verifying Installation

Quick Test

To verify Xenia is working correctly:

Launch Xenia

Start Xenia without any game to ensure it launches properly.

Check Graphics Backend

Look at the window title or log output to verify your graphics backend initialized:

[Vulkan] or [D3D12] should appear

Load a Test Game

Try loading a known-working game from the compatibility list.

Enable Logging

For troubleshooting, enable console logging:

# Windows
xenia_canary.exe --log_file=stdout game.xex

# Linux
./xenia --log_file=stdout game.xex

This will show detailed information about what Xenia is doing.

Next Steps

Quickstart Guide

Quick guide to running your first game

Configuration

Detailed configuration options

Command-Line Reference

All command-line flags and options

Compatibility List

Check which games work

Getting Help

If you encounter issues during installation:

Check the FAQ for common problems
Search existing GitHub issues
Join the Discord community for help
Report bugs with detailed logs and system information

Remember: Always ensure you have legal copies of any games you use with Xenia. Do not ask for or share copyrighted content.

Get Started

Building

Architecture

GPU Tools

Development

Reference

Installation

Installation Overview

Windows Installation

Linux Installation

System Requirements

Minimum Requirements

Recommended Requirements

Windows Installation

Option 1: Download Pre-Built Binary (Recommended)

Visual C++ Redistributables

Graphics Drivers

Option 2: Build from Source

Linux Installation

Prerequisites

Building Xenia

Linux Troubleshooting

Post-Installation Setup

Directory Structure

Configuration File

Making Xenia Portable

Updating Xenia

Pre-Built Binaries

Source Builds

Verifying Installation

Quick Test

Enable Logging

Next Steps

Quickstart Guide

Configuration

Command-Line Reference

Compatibility List

Getting Help

Build docs developers (and LLMs) love

Get Started

Building

Architecture

GPU Tools

Development

Reference

​Installation Overview

Windows Installation

Linux Installation

​System Requirements

​Minimum Requirements

​Recommended Requirements

​Windows Installation

​Option 1: Download Pre-Built Binary (Recommended)

​Visual C++ Redistributables

​Graphics Drivers

​Option 2: Build from Source

​Linux Installation

​Prerequisites

​Building Xenia

​Linux Troubleshooting

​Post-Installation Setup

​Directory Structure

​Configuration File

​Making Xenia Portable

​Updating Xenia

​Pre-Built Binaries

​Source Builds

​Verifying Installation

​Quick Test

​Enable Logging

​Next Steps

Quickstart Guide

Configuration

Command-Line Reference

Compatibility List

​Getting Help

Build docs developers (and LLMs) love

Installation Overview

System Requirements

Minimum Requirements

Recommended Requirements

Windows Installation

Option 1: Download Pre-Built Binary (Recommended)

Visual C++ Redistributables

Graphics Drivers

Option 2: Build from Source

Linux Installation

Prerequisites

Building Xenia

Linux Troubleshooting

Post-Installation Setup

Directory Structure

Configuration File

Making Xenia Portable

Updating Xenia

Pre-Built Binaries

Source Builds

Verifying Installation

Quick Test

Enable Logging

Next Steps

Getting Help