opsu! is an unofficial open-source client for the rhythm game osu!, written in Java using Slick2D and LWJGL (wrappers around OpenGL and OpenAL).

opsu! runs on Windows, OS X, and Linux. A libGDX port also supports Android devices.

Getting Started

Get a copy of opsu! from the releases page. APK releases can be found here.

Java Setup

The Java Runtime Environment (JRE) 7 or higher must be installed in order to run opsu!. The download page is located here.


opsu! requires "beatmaps" to run, which contain the songs and gameplay data. These can be downloaded directly through opsu! in the downloads menu, or manually from the osu! website (requires registration) and mirror sites like Bloodcat. Place any manually downloaded beatmaps (in .osz format) in the Import/ directory for opsu! to unpack them automatically.

If osu! is installed, opsu! will attempt to read beatmaps from the osu! installation location. The beatmap directory can also be changed by setting the "BeatmapDirectory" value in the generated configuration file.

First Run

opsu! will parse all beatmaps when launched, which can take a while for the first time. If no beatmaps are found, the game will prompt you to download some to get started.

Game settings can be changed in the options menu, accessed by clicking the "Other Options" button in the song menu. The "Music Offset" value will likely need to be adjusted initially, or whenever hit objects are out of sync with the music.

Directory Structure

The following files and folders will be created by opsu! as needed:


opsu! is distributed as both a Maven and Gradle project.


Maven builds are built to the target directory.


Gradle builds are built to the build directory.


See the contributing guidelines.


This software was created by Jeffrey Han (@itdelatrisu). All game concepts and designs are based on work by osu! developer Dean Herbert (@ppy). Other credits can be found here.


This software is licensed under GNU GPL version 3. You can find the full text of the license here.