How to Set Up Akatsuki Patcher with osu-winello: Complete Guide

To set up the Akatsuki patcher with osu-winello, run ./osu-wine --akatsuki after installation, which automatically downloads the patcher, installs required .NET dependencies, and launches the GUI to apply low-latency patches.

osu-winello is a Bash-driven installer that automates osu! stable setup on Linux. Setting up the Akatsuki patcher with this tool provides community-developed patches that reduce audio latency, fix alt-tab crashes, and improve overall performance without manual binary manipulation.

Understanding the osu-winello Architecture

The project uses two primary scripts to manage installation and runtime:

• osu-winello.sh – The core installer and updater. This script handles downloading external binaries including Wine-osu, gosumemory, and the Akatsuki patcher. It also prepares the Wine prefix and defines the akatsukiPatcher() function.
• osu-wine – A thin wrapper script that forwards command-line flags to functions in osu-winello.sh. It sets up runtime options, logging, and the execution environment for the game.

How the Akatsuki Patcher Integration Works

Flag Registration (--akatsuki)

In osu-wine, a case block at lines 308-311 registers the --akatsuki flag. When invoked, this flag triggers the akatsukiPatcher routine defined in osu-winello.sh.

Dependency Management (.NET Desktop Runtime 6)

The akatsukiPatcher function first verifies that .NET Desktop Runtime 6 exists in the Wine prefix. If absent, it automatically executes winetricks dotnetdesktop6 to satisfy this prerequisite before proceeding.

Download Mechanism

The patcher binary (akatsuki_patcher.exe) downloads from the hard-coded URL https://air_conditioning.akatsuki.gg/loader (stored as AKATSUKILINK in the source). The script saves this to $XDG_DATA_HOME/osuconfig/akatsukiPatcher/.

Execution Environment

Before launching, the script configures verbose logging via WINEDEBUG and redirects all output to $XDG_DATA_HOME/osuconfig/winello.log. It then executes the patcher through Wine, providing users with instructions on locating the osu! folder (mapped to D: drive) within the patcher interface.

Step-by-Step Setup Guide

1. Install osu-winello

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

   This clones the repository, makes the installer executable, and runs the full installation (downloading Wine-osu, creating the Wine prefix, and setting up optional components).

2. Ensure winetricks is available

   The installer automatically fetches winetricks if missing. If you need to run it manually later, use ./osu-wine --winetricks.

3. Launch the Akatsuki patcher

   ./osu-wine --akatsuki

   Or, if osu-wine is in your $PATH: osu-wine --akatsuki

   This triggers the akatsukiPatcher function, which installs .NET Desktop Runtime 6 if needed, downloads the latest akatsuki_patcher.exe, and starts it inside Wine.

4. Apply patches

   In the GUI that opens, navigate to Locate > My Computer > D: to point the patcher at your osu! installation (the script creates a D: drive mapping to the osu! folder). Click Open, then Patch.

   The patcher updates osu! binaries with the latest low-latency audio, alt-tab, and crash-fix patches.

5. Verify installation

   After the patcher exits, start the game:

   ./osu-wine

   You should see the updated version number in the osu! client, confirming the patches were applied successfully.

Connecting to Akatsuki Servers

If you want osu! to connect to an Akatsuki-hosted server instead of the official one, use the --devserver flag:

osu-wine --devserver akatsuki.gg

This tells the launch script to pass -devserver akatsuki.gg to the osu! executable itself, routing all game traffic to the specified private server.

Troubleshooting Common Issues

• Missing .NET runtime – The script attempts to install this automatically. If it fails, run winetricks dotnetdesktop6 manually and retry --akatsuki.

• Log file location – All patcher output is written to $XDG_DATA_HOME/osuconfig/winello.log. Review this file if the patcher crashes or reports "Runtime Platform missing".

• Permission errors – Ensure the install directory (~/.local/share/osuconfig) is writable and that you have execution rights on the downloaded .exe files.

• Patcher cannot find osu! – Remember that the script maps your osu! folder to the D: drive in Wine. Use My Computer > D: in the patcher GUI, not the default C: drive.

Summary

• osu-winello automates osu! installation on Linux through osu-winello.sh and the osu-wine wrapper.
• The --akatsuki flag triggers the akatsukiPatcher function, which handles .NET dependencies and downloads the patcher from https://air_conditioning.akatsuki.gg/loader.
• The patcher applies low-latency audio and stability fixes to your osu! installation.
• Use --devserver akatsuki.gg to connect to Akatsuki private servers after patching.

Frequently Asked Questions

What is the Akatsuki patcher and why do I need it?

The Akatsuki patcher is a community-developed tool that modifies osu! stable binaries to reduce audio latency, fix alt-tab crashes, and improve overall performance on Linux. According to the osu-winello source code, these patches are particularly beneficial for Wine-based installations where default Windows audio routing introduces additional latency.

Can I use the Akatsuki patcher on an existing osu! installation?

Yes. The akatsukiPatcher function in osu-winello.sh (lines 799-823) is designed to work with existing osu! installations managed by osu-winello. When you run ./osu-wine --akatsuki, the script automatically locates your osu! folder (mapped to the D: drive in Wine) and applies patches regardless of when you originally installed the game.

How do I switch between the official osu! server and Akatsuki servers?

Use the --devserver flag when launching the game. For example, osu-wine --devserver akatsuki.gg passes the -devserver akatsuki.gg argument directly to the osu! executable, routing all gameplay traffic to the Akatsuki private server. To return to official servers, simply launch without the flag: ./osu-wine.

What should I do if the patcher fails to start or crashes?

First, check the log file at $XDG_DATA_HOME/osuconfig/winello.log (typically ~/.local/share/osuconfig/winello.log). The most common issue is a missing .NET Desktop Runtime 6, which the script attempts to install automatically via winetricks dotnetdesktop6. If this fails, run osu-wine --winetricks dotnetdesktop6 manually, then retry ./osu-wine --akatsuki.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}