# osu-winello: running the stable osu! client on Linux with Wine

> osu-winello is a shell installer that sets up osu! on Linux using a patched wine-osu build, a prebuilt Wineprefix, and the Steam runtime container, and it handles the parts that usually make a Wine game install painful. It is GPL-3.0 licensed, it is a convenience wrapper rather than a new client, and it depends on 64-bit graphics drivers working properly.

**NelloKudo/osu-winello** — osu! stable installer for Linux with patched wine-osu and other nice features 8)

- Repository: https://github.com/NelloKudo/osu-winello
- Stars: 847 · Forks: 37
- Language: Shell
- License: GPL-3.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/nellokudo-osu-winello

## What the installer actually assembles

osu-winello describes itself as an osu! stable installer for Linux with patched wine-osu and other features, and the project description adds other nice features. It is a shell script, and the repository is small in structure: a LICENSE.md, the README, the osu-winello.sh installer, an osu-wine launcher script and a stuff directory.

The problem it solves is not running a game under Wine in the abstract. It is that a Wine installation of this particular game involves several pieces that have to be compatible with each other, and that the pieces are maintained separately by different people. This script pulls them together and keeps them updated together.

The pieces are visible in the feature list. The core is updatable patched wine-osu binaries, from the author's own WineBuilder releases, carrying the latest osu! patches for low-latency audio, better performance, alt-tab behavior, crash fixes and more. Then there is yawl, which runs wine-osu inside Steam's runtime container so you do not have to install Wine dependencies yourself. Then osu-handler for importing maps and skins, Discord RPC through rpc-bridge, and support for native file managers.

Beyond that, the installer handles the install path itself. It installs osu! on either the default or a custom path, selected through the zenity GUI, and it works for existing osu! installations coming from Windows. It ships Windows fonts pre-installed in the Wine prefix, covering Japanese fonts and special characters, and it uses the author's own fork of osu-wineprefix so you do not have to build one.

The last feature in the list is the one that tells you what kind of project this is. It skips the pain of downloading a Wineprefix.

For streaming and similar use, the installer supports the latest tosu and the legacy gosumemory with automatic install, which is a separate concern from playing the game locally and is a real convenience for a specific user group.

## Prerequisites: drivers first, then the small tools

The requirements list is short and honest. Besides 64-bit graphics drivers, the script needs git, zenity, wget, unzip and xdg-desktop-portal-gtk for in-game links. Each major distribution has a one-liner. On Ubuntu and Debian it is `sudo apt install -y git wget unzip zenity xdg-desktop-portal-gtk`, on Arch Linux `sudo pacman -Syu --needed  --noconfirm git wget unzip zenity xdg-desktop-portal-gtk`, on Fedora `sudo dnf install -y git wget unzip zenity xdg-desktop-portal-gtk`, on openSUSE `sudo zypper install -y git wget unzip zenity xdg-desktop-portal-gtk`, and on Void Linux `sudo xbps-install -S -y git wget unzip zenity xdg-desktop-portal-gtk xz`.

The xdg-desktop-portal-gtk piece is easy to skip and worth noticing, because it is what makes links inside the game open correctly rather than silently doing nothing.

The driver advice is given more prominence than the package list, which is the right emphasis. The documentation says installing drivers the right way is needed to have a great experience and to avoid poor performance or other problems, and that osu! needs 64-bit graphics drivers to run as it should, so if you are having performance problems it is probably related to that. The suggested packages are nvidia-utils or nvidia-driver for NVIDIA and libgl1-mesa-dri for AMD and Intel, with a link to the Lutris driver guide, and a fallback tip that installing Steam with your package manager will pull in the necessary drivers.

PipeWire is described as not really a dependency but highly recommended, especially with this script. You can check what you have with:

```
LANG=C pactl info | grep "Server Name"
```

If it reports Server Name: PulseAudio (on Pipewire) you are set, otherwise the wiki has instructions for installing PipeWire.

## Running the installer and launching the game

The install is a clone, a chmod and a run:

```
git clone https://github.com/NelloKudo/osu-winello.git
cd osu-winello
chmod +x ./osu-winello.sh
./osu-winello.sh
```

The script is interactive. It uses zenity to let you pick the install path, which is how the same script handles both a fresh install into the default location and pointing at an existing Windows osu! installation. The first run also sets up the Wineprefix and the runtime, which is why it takes a while.

Afterwards the game is launched with a single command:

```
osu-wine
```

Two warnings follow in the documentation. You might need to relaunch your terminal to launch the game, which is a PATH refresh issue after the installer writes its wrapper scripts. And you should use a global offset of -40 or 35ms to make up for Wine quirks, or -25 if you are using audio compatibility mode. The documentation is careful to add that these values work for most setups but your mileage may vary, and to keep an eye on the hit meter.

That offset advice is the honest signal about the state of the project. The script cannot remove the latency of running a Windows game under Wine, so it tells you how to compensate numerically. A rhythm game where input timing is the entire experience is the hardest possible case for a compatibility layer, and the project is candid that you may need to tune this per setup.

The launcher also has a substantial command surface, and the flags are the practical documentation of what the script sets up. Beyond the basics of --help, --info, --edit-config, --winecfg, --winetricks, --regedit, --wine <args>, --kill, --kill9, --update, --fixprefix, --fixfolders and --fix-yawl, there are two entries on the installer side, --no-deps to install the game but skip installing dependencies, and uninstall, plus a fix-yawl flag for partial downloads or corruption in the runtime files.

## Configuration through cfg files and environment variables

Customization happens in files rather than in a settings screen. Winello allows you to set launch arguments or custom environment variables using .cfg files located in:

```
~/.local/share/osuconfig/configs
```

An example.cfg file is provided, containing all supported environment variables along with usage instructions. To edit it you can use a text editor or the built-in shortcut:

```sh
nano ~/.local/share/osuconfig/configs/example.cfg
# or simply: osu-wine --edit-config
```

The two variables you are most likely to touch are PRE_LAUNCH_ARGS and POST_LAUNCH_ARGS. To add mangohud to the launch arguments you uncomment the existing PRE_LAUNCH_ARGS line, removing the #, or add a new one:

```sh
PRE_LAUNCH_ARGS="mangohud"
```

If you always want to run on a custom server, you edit POST_LAUNCH_ARGS in the same fashion, and an example of that is shown in the same file.

The split between the two is the useful detail. PRE_LAUNCH_ARGS injects arguments before the game starts, which is where a wrapper like mangohud or a performance overlay has to go. POST_LAUNCH_ARGS applies to the launch itself, which is where a server selection argument belongs. Getting that wrong means the game ignores your value, which is the sort of thing that sends people looking in the wrong place.

The --fixfolders flag covers a related integration point. It reconfigures osu-handler and native file integration, and the documentation says to run it if osu!direct, .osz or .osk handling, or opening folders and .osu or .osb files from within the game is broken. That is a wide range of file association plumbing, and having one command to rebuild it rather than a manual sequence of desktop file edits is a real convenience of the packaged approach.

## Where this approach falls short

The obvious boundary is that this is a wrapper around Wine, and Wine is the actual source of the friction.

The latency compensation is the clearest example. A -40 or 35ms global offset is a manual correction for a layer the project does not control, and a global offset is a blunt instrument in a game where the difference between a 30 and a 40 millisecond offset is perceptible to a good player. The documentation even tells you to watch the hit meter, which is an admission that the correct value is a matter of measurement rather than configuration.

The second boundary is the driver requirement. Everything the script does assumes 64-bit graphics drivers work correctly in your distribution, and when they do not, the symptom appears as poor game performance that no amount of reinstalling the prefix will fix. A user with a broken Mesa or NVIDIA setup will spend their time on the driver problem while the installer appears to be the suspect.

The third is the dependency chain. The script pulls a patched wine-osu build, the Steam runtime through yawl, osu-handler, rpc-bridge, and a Wineprefix fork, each from a separate upstream, and each with its own update cadence. The --update and --fix-yawl flags exist because that chain breaks, and the fix-yawl description mentions partial downloads and corruption. A self-contained installer that reaches into five other projects is not self-contained, and network hiccups during setup are the most likely first-run failure.

The fourth is scope. This installs the stable client. The osu!lazer client is a native .NET build with its own Linux story, and tosu and gosumemory are separate tools for streaming. If what you want is the lazer client, this script is the wrong tool even though it covers the same game.

Finally, the tutorial is thin. The documentation points to a wiki for performance optimization and troubleshooting, and a DeepWiki page summarizing what the script does, and it directs users to a Discord channel. That is a reasonable amount of documentation for a script this size, but it does mean the script itself is the thing you have to read if something goes wrong.

## Steam Deck support and the state of the project

The README's table of contents lists Steam Deck Support as its own section, alongside installation, features, customization, optimizations, troubleshooting and flags. The section body is not reproduced in the documentation available here, so the specifics of the Deck setup are not something this write-up can describe, and the wiki is the place to look.

What is clear from the rest of the document is that the Steam Deck is the design centre of the project. The yawl integration, which runs wine-osu inside Steam's runtime container, is the same mechanism that makes the Steam Deck a good target: the runtime supplies the graphics stack and libraries so you do not have to install a full Wine dependency set on a handheld with limited disk. SteamOS is also the environment where a Wine-based game is most likely to work without friction, because the compatibility layer is already part of the platform.

On maintenance, the repository is not archived and the last push was on 2026-10-19, so work is recent. The only listed release is winello-bins, described as the osu-winello archive, dated 2025-03-18. That is a release of binaries rather than a versioned script release, and the versioning here is a little unusual, since the project ships as a script you clone and run rather than as a package.

The licence is GPL-3.0, with the LICENSE.md at the repository root. For a user this carries no practical obligation, since you are running a script you fetched rather than distributing a modified work, and for anyone who does fork it to support another distribution the copyleft means the changes stay open, which is the outcome that helps the next person with an unsupported setup.

The credits section and the Discord support route point to a community that sustains the project, and the DeepWiki link is a reasonable place to get an overview of the script's logic before reading the shell code itself.

## Conclusion

Adopt osu-winello if you want the stable osu! client on Linux and do not want to assemble a Wineprefix, a patched wine build and the Steam runtime yourself. Do not adopt it for the lazer or osu!lazer clients, since this targets the stable branch, and skip it if your graphics drivers are not set up, because the script will not fix that. Verify first that your system has 64-bit drivers working, that PipeWire is present rather than PulseAudio, and that you read the wiki pages on performance optimization and troubleshooting before blaming the game for a stutter.

## FAQ

### How do I install osu! on Linux with osu-winello?

Clone the repository, make the script executable and run it: `git clone https://github.com/NelloKudo/osu-winello.git`, then `cd osu-winello`, `chmod +x ./osu-winello.sh` and `./osu-winello.sh`. The script uses zenity to let you pick the install path, and you launch the game afterwards with `osu-wine`.

### What dependencies does osu-winello need?

Besides 64-bit graphics drivers it needs git, zenity, wget, unzip and xdg-desktop-portal-gtk. The README gives an install line for Ubuntu and Debian, Arch Linux, Fedora, openSUSE and Void Linux, and PipeWire is described as highly recommended rather than required.

### What global offset should I use for osu! under Wine?

The documentation suggests -40 or 35ms to make up for Wine quirks, or -25 if you use audio compatibility mode, and notes that these values work for most setups but your mileage may vary. It advises keeping an eye on the hit meter.

### How do I add launch arguments or custom environment variables in osu-winello?

Edit the .cfg files in ~/.local/share/osuconfig/configs, where an example.cfg file ships with all supported environment variables. You can open it with a text editor or with `osu-wine --edit-config`, and set values such as PRE_LAUNCH_ARGS="mangohud" or POST_LAUNCH_ARGS for a custom server.

### What is the difference between the osu-winello and osu-wine scripts?

osu-winello.sh is the installation script and takes the flags --no-deps, uninstall and fix-yawl. osu-wine is the launcher you use to run the game and it carries the runtime flags such as --info, --edit-config, --update, --fixprefix, --fixfolders and --fix-yawl.

## Sources

- [Issues](https://github.com/NelloKudo/osu-winello/issues)
- [License: GPL-3.0](https://github.com/NelloKudo/osu-winello/blob/main/LICENSE)
- [NelloKudo/osu-winello on GitHub](https://github.com/NelloKudo/osu-winello)
- [README](https://github.com/NelloKudo/osu-winello/blob/main/README.md)
- [Releases](https://github.com/NelloKudo/osu-winello/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nellokudo-osu-winello