Guide · Open source

How to use osu: install lazer, build it and run it

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

osu! is a free-to-play rhythm game where you click, tap, and follow objects in time with music. This repository contains "lazer", the open-source successor to the osu! game client, released under the MIT license. This guide shows you how to get the source, build it from the command line and run the game, plus where to look if you want to develop rulesets or contribute.

osu!ppy/osu · ★ 19.4k · MIT Install options & downloads

Quick start

1Install the .NET SDK. Install the correct .NET SDK for your desktop platform from the official .NET download page.
2Clone the repository. Run git clone https://github.com/ppy/osu in your terminal.
3Enter the directory. Run cd osu to move into the project folder.
4Build and run. Run dotnet run --project osu.Desktop to build and launch the game.
5Update later. Run git pull inside the osu directory to fetch the latest commit.

What you need before you start

The source README lists one prerequisite for building from source: a desktop platform with the correct .NET SDK installed. You can download the SDK from the official .NET download page linked in the project README.

If you only want to play rather than build, the README lists prebuilt releases for Windows 10+ (x64), macOS 12+ (Intel and Apple Silicon), Linux (x64), iOS 13.4+ and Android 7+.

Desktop platform with the .NET SDK installed
Git, to clone the repository

Download the source code

Clone the repository with git, then move into the project folder. To update later, run git pull inside the osu directory.

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

git pull

Build and run osu! from the command line

The README gives a single command to build and run the desktop game. For performance testing, add -c Release to the build command, because the default Debug configuration can be much slower. If the build fails, try restoring NuGet packages with dotnet restore.

If the build fails, run dotnet restore and try again.
For performance testing, add -c Release.

dotnet run --project osu.Desktop

Open the project in an IDE

The README recommends loading the solution through a platform-specific .slnf file rather than the main .sln, because this reduces dependencies and hides platforms you do not need. The recommended IDEs are Visual Studio, JetBrains Rider, and Visual Studio Code with the EditorConfig and C# Dev Kit extensions.

osu.Desktop.slnf (most common)
osu.Android.slnf
osu.iOS.slnf
For mobile builds, you may need to run sudo dotnet workload restore first to install Android or iOS tooling.

Run the code analysis tools before committing

The README asks contributors to run a code formatter before committing. You can run dotnet format from the command line or use the Format code command in your IDE. A ReSharper InspectCode script is also provided for wider rule sets.

Run dotnet format
Or use Format code in your IDE
On Windows, run .\InspectCode.ps1 for ReSharper InspectCode

dotnet format

Build custom rulesets

osu! is designed to allow user-created gameplay variations called rulesets. A ruleset lets a developer use the osu! beatmap library, game engine and general UX for a new style of gameplay. The README links templates to start from and a discussion thread with examples of custom rulesets.

Templates are in the Templates folder of the repository.
Examples are in the custom ruleset directory discussion on GitHub.

What people use it for

Playing the open-source lazer client alongside the stable osu! client
Trying out a custom rhythm gameplay ruleset built on the osu! framework
Running performance tests using a Release build
Contributing bug fixes or features to a large C# game codebase

Frequently asked questions

Is osu! free?

The README describes osu! as a free-to-play rhythm game and says this repository's code and framework are licensed under the MIT license. It also notes that the osu! and ppy branding and game resources are covered separately.

What license is osu lazer under?

The code and framework are under the MIT license. The README says you can do what you want as long as you include the original copyright and license notice. The osu! and ppy branding is protected by trademark law and is not covered by that license.

What do I need to build osu from source?

You need a desktop platform with the correct .NET SDK installed. Then clone the repository and run dotnet run --project osu.Desktop from the osu folder.

Which platforms does osu lazer support?

The README lists prebuilt releases for Windows 10+ (x64), macOS 12+ (Intel and Apple Silicon), Linux (x64), iOS 13.4+ and Android 7+. It says other platforms may still run the release or be built manually, but it does not list them.

Should I use osu lazer or the stable osu! client?

The README says players are encouraged to install lazer alongside their stable osu! client. It also says lazer is still under constant development and is not yet preferred by most users, so the stable client may be the safer choice for a standard experience.

What should I do if the build fails?

The README says to try restoring NuGet packages with dotnet restore. If you are building mobile targets, you may also need sudo dotnet workload restore to install the Android or iOS tooling.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose osu! lazer if you want a free, open-source rhythm game client, want to try the newer client, or plan to build rulesets or work on a large C# codebase. Pick the stable osu! client if you just want the established experience, or skip this project if your platform is unsupported and you have no build experience.

Install options & downloads