Skip to main content

​
Building osu!

This guide covers how to build and run osu! from source code using different methods.

​
Building from CLI

​
Quick Start

The fastest way to build and run osu! is with a single command: 
dotnet run --project osu.Desktop
This will:
  1. Restore NuGet packages
  2. Build the project
  3. Run the game

​
Release Build

Always use Release configuration for performance testing.
When running locally for performance testing, use the Release configuration: 
dotnet run --project osu.Desktop -c Release
The Debug configuration has significant overhead, especially when testing with local framework modifications.

​
Restoring NuGet Packages

If the build fails, try restoring NuGet packages manually: 
dotnet restore

​
Building from an IDE

1

Open the solution file

Load the appropriate platform-specific .slnf file:
osu.Desktop.slnf
2

Use IDE build functionality

Use the provided Build/Run functionality in your IDE:
  • Visual Studio: Press F5 or click Start
  • Rider: Use the Run button or Shift+F10
  • VS Code: Use the Run and Debug panel
3

Run tests (recommended)

When testing or building new components, use the osu! (Tests) project/configuration.This provides a faster feedback loop for development.

​
Build Configuration

The project uses these key configuration files:

​
global.json

{
  "sdk": {
    "version": "8.0.100",
    "rollForward": "latestFeature",
    "allowPrerelease": false
  }
}

​
Directory.Build.props

Key settings:
  • Language Version: C# 12.0
  • Nullable: Enabled
  • Code Analysis: Multiple analyzers enabled
  • Documentation: XML documentation generated for all projects

​
Testing with Local Framework Modifications

You can cross-test changes in osu-resources or osu-framework locally.
Sometimes you may need to test changes in osu-resources or osu-framework. Use these scripts: 
UseLocalFramework.ps1
UseLocalResources.ps1

​
Project Structure Required

These commands assume you have projects checked out in adjacent directories: 
|- osu            // this repository
|- osu-framework
|- osu-resources

​
Code Analysis

Before committing code, run the code formatter: 
dotnet format

​
Additional Analysis Tools

The project uses several code analysis tools:
  • Cross-platform analyzers: Integrated into the compiler, provide warnings during editing and building
  • JetBrains ReSharper InspectCode: Run with ./InspectCode.ps1 or use Rider for inline support

​
Build Targets

​
Desktop Platforms

Windows

Windows 10+ (x64) - Primary development platform

macOS

macOS 12+ (Intel and Apple Silicon)

Linux

Linux (x64) via AppImage

​
Mobile Platforms

Mobile builds require running sudo dotnet workload restore first.
  • Android: 5+
  • iOS/iPadOS: 13.4+

​
Troubleshooting

​
Build Failures

  1. Restore packages: dotnet restore
  2. Clean build: dotnet clean && dotnet build
  3. Check SDK version: dotnet --version should be 8.0.100+

​
Performance Issues

  • Ensure you’re using Release configuration: -c Release
  • Check for Debug mode overhead in your IDE settings

​
Mobile Build Issues

Run the workload restore command: 
sudo dotnet workload restore

​
Next Steps

Architecture

Learn about the codebase structure

Contributing

Read the contribution guidelines

Build docs developers (and LLMs) love

Get started for freeTalk to us