Skip to main content

​
Installation

This guide provides detailed installation instructions for osu! (lazer) on all supported platforms.
This is the final iteration of osu!, released under the codename “lazer”. It’s designed to run alongside the stable osu! client during the transition period.

​
Windows

​
Requirements

  • Windows 10 or later (x64)
  • Windows 8.1 may work but is not officially supported
osu! requires at least Windows 8.1 to run due to database dependencies. If you’re running a newer version of Windows and encounter errors, ensure “Compatibility mode” is not enabled for osu!.

​
Installation steps

1

Download the installer

Download the Windows installer:
https://github.com/ppy/osu/releases/latest/download/install.exe
2

Run the installer

Double-click install.exe to launch the installer. Follow the on-screen instructions.The installer uses Velopack for automatic updates and will:
  • Install osu! to your user directory
  • Create desktop and start menu shortcuts
  • Set up file associations for .osz, .osk, and .osr files
3

Launch osu!

Start osu! from the desktop shortcut or Start menu. The game will run its first-time setup and check for updates.

​
File associations

On first run, osu! automatically registers file associations for:
  • .osz - Beatmap archives
  • .osk - Skin archives
  • .osr - Replay files
You can now double-click these files to import them directly into osu!.

​
macOS

​
Requirements

  • macOS 12 (Monterey) or later
  • Intel or Apple Silicon processor

​
Installation steps

1

Download the correct version

Choose the appropriate version for your Mac:Intel Macs:
https://github.com/ppy/osu/releases/latest/download/osu.app.Intel.zip
Apple Silicon (M1/M2/M3):
https://github.com/ppy/osu/releases/latest/download/osu.app.Apple.Silicon.zip
Not sure which processor you have? Click the Apple menu → About This Mac. If it shows “Apple M1”, “Apple M2”, or “Apple M3”, use the Apple Silicon version.
2

Extract the application

Double-click the downloaded .zip file to extract osu!.app.
3

Move to Applications folder

Drag osu!.app to your Applications folder.
4

First launch

Right-click osu!.app and select “Open” to bypass Gatekeeper on first launch.
macOS may show a security warning because osu! is not notarized by Apple. Click “Open” to proceed.

​
Linux

​
Requirements

  • Modern Linux distribution (x64 architecture)
  • .NET 8.0 runtime (included in AppImage)

​
Installation with AppImage

1

Download the AppImage

wget https://github.com/ppy/osu/releases/latest/download/osu.AppImage
2

Make it executable

chmod +x osu.AppImage
3

Run osu!

./osu.AppImage
Optionally, move it to a directory in your PATH:
mv osu.AppImage ~/.local/bin/osu

​
Building from source

For unsupported platforms or custom builds, you can compile osu! from source:
1

Install prerequisites

Install the .NET 8.0 SDK:
# Ubuntu/Debian
sudo apt-get install -y dotnet-sdk-8.0

# Fedora
sudo dnf install dotnet-sdk-8.0

# Arch Linux
sudo pacman -S dotnet-sdk
2

Clone the repository

git clone https://github.com/ppy/osu
cd osu
3

Build and run

Build the desktop client:
dotnet run --project osu.Desktop
For better performance, build in Release mode:
dotnet run --project osu.Desktop -c Release

​
iOS

​
Requirements

  • iOS 13.4 or later
  • iPhone or iPad

​
Installation via TestFlight

1

Install TestFlight

Download TestFlight from the App Store if you don’t have it already.
2

Join the beta

Visit the TestFlight link:
https://osu.ppy.sh/home/testflight
The TestFlight beta has a hard limit of 10,000 users. If it’s full, check back regularly or follow @ppy on Twitter for announcements about resets.
3

Install osu!

Open the TestFlight link on your iOS device and tap “Install” to download osu!.

​
Android

​
Requirements

  • Android 5.0 (Lollipop) or later

​
Installation steps

1

Download the APK

https://github.com/ppy/osu/releases/latest/download/sh.ppy.osulazer.apk
2

Enable installation from unknown sources

Go to Settings → Security and enable “Install from unknown sources” or “Unknown sources”.On Android 8.0+, you’ll be prompted to allow installation from your browser when you open the APK.
3

Install the APK

Open the downloaded APK file and tap “Install”.
4

Launch osu!

Open osu! from your app drawer and start playing!

​
Development setup

If you want to contribute to osu! or build custom features, follow these steps:

​
Prerequisites

# Install .NET 8.0 SDK
winget install Microsoft.DotNet.SDK.8

# Install Visual Studio 2022 (recommended)
winget install Microsoft.VisualStudio.2022.Community

​
Clone and build

1

Clone the repository

git clone https://github.com/ppy/osu
cd osu
2

Restore dependencies

dotnet restore
3

Build from IDE or CLI

Using an IDE: Open the platform-specific solution file:
  • osu.Desktop.slnf - Desktop development (most common)
  • osu.Android.slnf - Android development
  • osu.iOS.slnf - iOS development
Using CLI:
dotnet run --project osu.Desktop
Use -c Release for performance testing:
dotnet run --project osu.Desktop -c Release
4

Mobile development (optional)

For Android/iOS development, install the required workloads:
sudo dotnet workload restore
  • Visual Studio 2022 (Windows) - Full-featured C# IDE
  • JetBrains Rider (Cross-platform) - Premium C# IDE
  • Visual Studio Code (Cross-platform) - Lightweight with C# Dev Kit
Install the EditorConfig extension for consistent code formatting.

​
Troubleshooting

​
Build failures

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

​
Multiple instances

osu! does not support running multiple instances simultaneously (except in debug builds). If you try to launch a second instance, it will send files to the existing instance via IPC.

​
Updates

On Windows and macOS, osu! uses Velopack for automatic updates. The game will check for updates on startup and download them in the background.
If updates are managed by an external package manager (e.g., Flatpak, AUR), automatic updates will be disabled.

​
Next steps

Contributing guide

Learn how to contribute code to osu!

Custom rulesets

Create your own game mode with custom rulesets

Build docs developers (and LLMs) love

Get started for freeTalk to us