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

> Learn how to set up Akatsuki patcher with osu-winello by running a simple command. This guide details automatic downloads, dependency installation, and applying low-latency patches for a better osu experience.

- Repository: [NelloKudo/osu-winello](https://github.com/nellokudo/osu-winello)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/nellokudo/osu-winello/blob/main/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`](https://github.com/nellokudo/osu-winello/blob/main/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`](https://github.com/nellokudo/osu-winello/blob/main/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**

   ```bash
   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**

   ```bash
   ./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:

   ```bash
   ./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:

```bash
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`](https://github.com/nellokudo/osu-winello/blob/main/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`](https://github.com/nellokudo/osu-winello/blob/main/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`.