# How Wineprefix Works in osu-winello: Complete Management Guide

> Manage your osu-winello Wineprefix effectively. Learn how this Wineprefix emulates a Windows environment for osu! and how to control it with osu-winello commands.

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

---

**osu-winello runs osu! inside a dedicated Wineprefix—a self-contained directory that emulates a Windows environment—located by default at `~/.local/share/wineprefixes/osu-wineprefix` and managed through the `osu-wine` launcher commands.**

The osu-winello project provides a scripted Wine environment for running osu! on Linux. Understanding how the Wineprefix functions is essential for troubleshooting broken installations, migrating game data, or customizing your setup beyond the defaults.

## What Is a Wineprefix in osu-winello?

A **Wineprefix** is an isolated directory that contains a complete Windows user profile, registry hives, virtual drive layout (`drive_c`), and all libraries required to run osu!. In `osu-winello`, this environment is pre-configured with specific Windows components (dotnet48, DXVK, fonts) to ensure compatibility without manual winetricks configuration.

## Default Wineprefix Location and Structure

When the launcher starts, it sets the prefix path using the `XDG_DATA_HOME` environment variable. In [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) (lines 76-78), the default is defined as:

```bash
export WINEPREFIX="${WINEPREFIX:-"$XDG_DATA_HOME/wineprefixes/osu-wineprefix"}"

```

Since `$XDG_DATA_HOME` typically defaults to `~/.local/share`, the standard prefix directory becomes:

```

~/.local/share/wineprefixes/osu-wineprefix

```

To verify your active prefix location at any time, run:

```bash
osu-wine --info

```

This outputs the current `Wineprefix location:` along with other environment details.

## How the Wineprefix Is Created

During a full installation ([`./osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/./osu-winello.sh)), the script checks for an existing Windows registry at `$WINEPREFIX/system.reg`. If missing, it downloads a pre-configured archive and extracts it. From [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) (lines 75-87):

```bash
DownloadFile "${PREFIXLINK}" "$HOME/.winellotmp/osu-winello-prefix.tar.xz"
tar -xf "$HOME/.winellotmp/osu-winello-prefix.tar.xz" -C "$XDG_DATA_HOME/wineprefixes"
mv "$XDG_DATA_HOME/wineprefixes/osu-prefix" "$XDG_DATA_HOME/wineprefixes/osu-wineprefix"

```

After extraction, the `reconfigurePrefix` function automatically executes, running winetricks to install **dotnet48**, **gdiplus**, **dxvk**, and other dependencies required for osu!.

## Managing and Repairing the Wineprefix

### Checking Current Location

Use the built-in info command to confirm where your prefix resides:

```bash
osu-wine --info

```

### Repair and Recreation

If osu! crashes or the prefix becomes corrupt, you have two repair options:

**Complete Rebuild:** Download a fresh prefix archive and reconfigure:

```bash
osu-wine --fixprefix

```

This calls `reconfigurePrefix fresh` (lines 491-511), which wipes the existing `$WINEPREFIX` directory and rebuilds it from scratch using winetricks.

**Partial Repair:** Re-run winetricks components without redownloading the base archive. When running `--fixprefix`, respond **"N"** to the redownload prompt. This invokes `reconfigurePrefix nowinepath`, which skips the archive extraction and only reinstalls missing libraries.

**Manual Deletion:** For complete manual control, delete the directory and trigger recreation:

```bash
rm -rf "$XDG_DATA_HOME/wineprefixes/osu-wineprefix"
osu-wine --fixprefix

```

### Uninstallation

When running `osu-wine uninstall`, the script prompts for prefix deletion (lines 1004-1008):

```bash
read -r -p "Do you want to uninstall Wineprefix? (y/N)" wineprch
[ "$wineprch" = 'y' ] && rm -rf "$XDG_DATA_HOME/wineprefixes/osu-wineprefix"

```

Answering **"y"** removes the entire Wineprefix directory.

## Changing the Wineprefix Location

You can relocate the prefix by setting the `WINEPREFIX` environment variable **before** launching osu!:

```bash
export WINEPREFIX="/mnt/games/osu-prefix"
osu-wine

```

For permanent changes, add the export to a configuration file in `~/.local/share/osuconfig/configs/`. The launcher sources all `*.cfg` files on startup (see `osu-wine`, lines 15-16):

```bash

# custom-location.cfg

export WINEPREFIX="${HOME}/Games/osu-winello-prefix"

```

## The reconfigurePrefix Function Internals

The `reconfigurePrefix` function in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) (lines 492-511) handles all prefix maintenance:

```bash
reconfigurePrefix() {
    while [[ $# -gt 0 ]]; do

        case "$1" in
            nowinepath) nowinepath=1 ;;
            fresh)      freshprefix=1 ;;
        esac
        shift
    done

    installWinetricks
    [ -n "$freshprefix" ] && {
        "$WINESERVER" -k
        rm -rf "$WINEPREFIX"
        "$WINETRICKS" -q nocrashdialog autostart_winedbg=disabled \
            dotnet48 dotnet20 gdiplus_winxp meiryo dxvk win10
    }
    folderFixSetup && discordRpc
    [ -z "$nowinepath" ] && saveOsuWinepath
}

```

- **`fresh` flag:** Kills Wine processes, deletes `$WINEPREFIX`, and reinstalls core components via winetricks.
- **`nowinepath` flag:** Skips the archive download and registry wipe, only running auxiliary setup (`folderFixSetup`, `discordRpc`).
- **Components installed:** dotnet48, dotnet20, gdiplus_winxp, meiryo font, DXVK, and Windows 10 version settings.

## Common Wineprefix Management Commands

| Goal | Command | Details |
|------|---------|---------|
| **Locate prefix** | `osu-wine --info` | Displays current `$WINEPREFIX` path |
| **Rebuild completely** | `osu-wine --fixprefix` | Downloads fresh archive and runs winetricks |
| **Repair components only** | `osu-wine --fixprefix` (answer N to download) | Runs `reconfigurePrefix nowinepath` |
| **Manual deletion** | `rm -rf "$XDG_DATA_HOME/wineprefixes/osu-wineprefix"` | Removes directory; next launch recreates it |
| **Custom location (session)** | `export WINEPREFIX="/path/to/prefix" && osu-wine` | Overrides default temporarily |
| **Custom location (permanent)** | Add `export WINEPREFIX="/path"` to `~/.local/share/osuconfig/configs/custom.cfg` | Persisted across launches |
| **Browse prefix files** | `wine explorer "$WINEPREFIX/drive_c"` | Opens Windows Explorer inside the prefix |

## Summary

- The default Wineprefix resides at `~/.local/share/wineprefixes/osu-wineprefix`, defined by `XDG_DATA_HOME` in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh).
- Initial creation downloads `osu-winello-prefix.tar.xz` and extracts it, followed by automated winetricks configuration via `reconfigurePrefix`.
- Use `osu-wine --fixprefix` to repair corruption, choosing between a full rebuild (`fresh`) or component-only repair (`nowinepath`).
- Override the default location by exporting `WINEPREFIX` or setting it in `~/.local/share/osuconfig/configs/*.cfg`.
- The `reconfigurePrefix` function manages all prefix state, installing dotnet48, DXVK, and required fonts through winetricks.

## Frequently Asked Questions

### Where is the osu-winello Wineprefix stored by default?

The prefix defaults to `$XDG_DATA_HOME/wineprefixes/osu-wineprefix`, which typically resolves to `~/.local/share/wineprefixes/osu-wineprefix` on most Linux distributions. You can confirm the exact path by running `osu-wine --info`.

### How do I completely reset the Wineprefix if osu! won't launch?

Run `osu-wine --fixprefix` and confirm the redownload when prompted. This executes `reconfigurePrefix fresh`, which deletes the existing prefix and rebuilds it from the pre-packed archive. Alternatively, manually run `rm -rf "$XDG_DATA_HOME/wineprefixes/osu-wineprefix"` followed by `osu-wine --fixprefix`.

### Can I move the Wineprefix to a different drive to save space?

Yes. Set a custom path by exporting `WINEPREFIX="/new/path/osu-prefix"` before running `osu-wine`, or create a file in `~/.local/share/osuconfig/configs/` containing `export WINEPREFIX="/new/path/osu-prefix"`. The launcher sources all `.cfg` files on startup, making the change persistent.

### What Windows components does the reconfigurePrefix function install?

When rebuilding with the `fresh` flag, `reconfigurePrefix` runs winetricks to install **dotnet48**, **dotnet20**, **gdiplus_winxp**, **meiryo** (Japanese font), **dxvk**, and sets the Windows version to **win10**. These components are essential for osu! audio, rendering, and text display under Wine.