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

> Master wine-osu-cachy with osu-winello. This guide shows how to set WINE_USE_CACHY=true for seamless osu setup and optimized performance. Get started now.

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

---

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

   ```bash
   osu-wine --edit-config
   ```

2. Locate the line:

   ```text
   ## WINE_USE_CACHY="true"

   ```

3. Remove the leading comment characters to uncomment:

   ```text
   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:

```bash
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`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh), the routine performs the following:

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

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

```bash
cat "$XDG_DATA_HOME/osuconfig/winello.log"

```

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

```text
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`](https://github.com/nellokudo/osu-winello/blob/main/stuff/example.cfg) | Template showing the `WINE_USE_CACHY` variable. | [Lines 14-16](https://github.com/NelloKudo/osu-winello/blob/main/stuff/example.cfg#L14-L16) |
| `osu-wine` | Runtime script that checks the flag and exports wine paths. | [Lines 16-21](https://github.com/NelloKudo/osu-winello/blob/main/osu-wine#L16-L21) |
| [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) | Contains `WineCachySetup()` and the `WINECACHYLINK` definition. | [Lines 19, 47-56](https://github.com/NelloKudo/osu-winello/blob/main/osu-winello.sh#L47-L56) |

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