How to Use wine-osu-cachy with osu-winello: A Complete Setup Guide

Set WINE_USE_CACHY="true" in your osu-winello configuration to automatically download, extract, and run osu! using the optimized wine-osu-cachy build based on wine-cachyos.

The osu-winello project simplifies running osu! on Linux, and now supports the alternative wine-osu-cachy runtime derived from wine-cachyos and wine-valve for enhanced performance. This guide covers the exact steps to enable this low-latency wine build by configuring environment variables and understanding the automated setup architecture implemented in the NelloKudo/osu-winello repository.

Architecture of the Cachy Integration

The integration relies on a conditional setup flow that checks for the WINE_USE_CACHY flag before launching. When enabled, the script orchestrates a download and wrapper registration process.

Core components:

• stuff/example.cfg – The template configuration file containing the WINE_USE_CACHY flag at lines 14-16.
• osu-wine – The runtime entry point that reads the flag and exports $WINE and $WINE_INSTALL_PATH to point at the cachy directories (lines 16-21).
• WineCachySetup() – A function defined in osu-winello.sh (lines 47-56) that handles the tarball download, extraction to $XDG_DATA_HOME/osuconfig/wine-osu-cachy-10.0, and yawl wrapper registration.
• yawl wrapper – A thin wrapper registered as winello-cachy that transparently routes calls to $WINE_INSTALL_PATH/bin/wine.

Execution flow:

1. The user runs osu-wine.
2. The script sources the config and detects WINE_USE_CACHY="true".
3. MainScript winecachy-setup triggers WineCachySetup().
4. The function downloads the pre-built binary, extracts it, and registers the wrapper.
5. $WINE is exported to the cachy binary path, and LaunchOsu() proceeds with the alternative runtime.

Enabling wine-osu-cachy in Your Configuration

You can enable the cachy build permanently via the configuration file or temporarily for a single session.

Permanent activation via config file

Configuration files reside in $XDG_DATA_HOME/osuconfig/configs (typically ~/.local/share/osuconfig/configs).

1. Open the configuration editor:

   osu-wine --edit-config

2. Locate the line:

   ## WINE_USE_CACHY="true"
   

3. Remove the leading comment characters to uncomment:

   WINE_USE_CACHY="true"

4. Save and exit. The file is automatically sourced on every subsequent launch.

One-off activation (temporary)

To test the cachy build without modifying config files, export the variable inline:

WINE_USE_CACHY=true osu-wine

This triggers the setup routine for that session only, without persisting the change.

First-Time Download and Installation

When you launch osu-wine with the flag enabled for the first time, the script executes WineCachySetup() automatically. According to the source code in osu-winello.sh, the routine performs the following:

1. Download – Fetches the tarball from the URL defined at line 19:

   WINECACHYLINK="https://github.com/NelloKudo/WineBuilder/releases/download/wine-osu-cachyos-v10.0-3/wine-osu-cachy-winello-fonts-wow64-10.0-3-x86_64.tar.xz"

2. Extraction – Unpacks the archive to $XDG_DATA_HOME/osuconfig/wine-osu-cachy-10.0.

3. Wrapper registration – Creates a yawl wrapper with make_wrapper=winello-cachy pointing to the extracted bin/wine binary.

No manual intervention is required beyond ensuring an active internet connection for the initial download.

Daily Usage with the Cachy Build

Once the setup completes, every standard osu-wine command transparently uses the cachy binary.

Common commands:

• osu-wine – Launch osu! using the wine-osu-cachy runtime.
• osu-wine --winecfg – Open winecfg for the cachy wine prefix.
• osu-wine --regedit – Open regedit for the cachy wine prefix.
• osu-wine --edit-config – Toggle the WINE_USE_CACHY setting.

Verification:

Check the runtime log to confirm the correct binary is active:

cat "$XDG_DATA_HOME/osuconfig/winello.log"

You should see an entry indicating the cachy path, such as:

Using wine: /home/username/.local/share/osuconfig/wine-osu-cachy-10.0/bin/wine

Key Source Files and Functions

Understanding these specific files helps with troubleshooting and advanced configuration:

File	Purpose	Key Location
stuff/example.cfg	Template showing the WINE_USE_CACHY variable.	Lines 14-16
osu-wine	Runtime script that checks the flag and exports wine paths.	Lines 16-21
osu-winello.sh	Contains WineCachySetup() and the WINECACHYLINK definition.	Lines 19, 47-56

Summary

• Set WINE_USE_CACHY="true" in $XDG_DATA_HOME/osuconfig/configs/example.cfg to enable the feature.
• The first launch automatically executes WineCachySetup(), downloading and extracting wine-osu-cachy version 10.0-3.
• A yawl wrapper (winello-cachy) is registered to transparently route wine calls to the cachy binary.
• All standard osu-wine commands work identically once the flag is active.
• Use WINE_USE_CACHY=true osu-wine for temporary testing without permanent configuration changes.

Frequently Asked Questions

What is wine-osu-cachy and how does it differ from the default wine build?

wine-osu-cachy is a specialized Wine build based on wine-cachyos and wine-valve, optimized for low latency and gaming performance. Unlike the standard wine build included with osu-winello, it incorporates specific patches from the CachyOS project designed to reduce input lag and improve frame timing for rhythm games.

Do I need to manually download the wine-osu-cachy binary?

No. When you set WINE_USE_CACHY="true" and run osu-wine, the WineCachySetup() function in osu-winello.sh automatically downloads the correct tarball from the official WineBuilder releases, extracts it to $XDG_DATA_HOME/osuconfig/wine-osu-cachy-10.0, and configures the necessary wrappers without requiring manual file management.

Can I revert to the standard wine build after enabling wine-osu-cachy?

Yes. Simply edit your configuration file using osu-wine --edit-config, comment out the WINE_USE_CACHY="true" line by adding ## at the beginning, or delete the line entirely. The next launch will revert to the default wine runtime paths exported by the standard launch sequence in osu-wine.

Where exactly is the wine-osu-cachy binary installed on my system?

The binary is extracted to $XDG_DATA_HOME/osuconfig/wine-osu-cachy-10.0 (typically ~/.local/share/osuconfig/wine-osu-cachy-10.0). The actual wine executable resides at bin/wine within this directory, and the osu-wine script exports this path to the $WINE environment variable when the cachy flag is enabled.

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