How Wineprefix Works in osu-winello: Complete Management Guide

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 (lines 76-78), the default is defined as:

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:

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), 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 (lines 75-87):

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:

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:

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:

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):

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!:

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):

# custom-location.cfg

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

The reconfigurePrefix Function Internals

The reconfigurePrefix function in osu-winello.sh (lines 492-511) handles all prefix maintenance:

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.
• 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.

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