How to Use Custom Installation Directories in osu-winello: A Complete Guide

You can install osu! to any folder on your Linux system using osu-winello's changedir command, which updates the OSUPATH variable and reconfigures Wine symlinks automatically.

The nellokudo/osu-winello project provides a Wine-based wrapper for running osu! on Linux, and it supports fully customizable installation locations beyond the default $XDG_DATA_HOME/osu-wine path. By leveraging the installOrChangeDir function and related path management routines, you can store your game files on a separate drive, a larger partition, or any directory structure you prefer while maintaining proper Wine integration.

Setting Up a Custom Installation Directory

Using the changedir Command

To trigger the custom directory workflow, run the installer script with the changedir sub-command. This invokes the installOrChangeDir function defined in [osu-winello.sh](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh#L63-L89).

The function provides two modes of operation:

• Interactive mode – Opens a graphical folder picker via zenity if no path is provided
• CLI mode – Accepts a direct filesystem path as the first argument

If the selected folder does not contain osu!.exe, the script automatically creates an osu! subfolder to house the game files.

# Launch the graphical folder picker

$ ./osu-winello.sh changedir

# Or specify the path directly (no GUI)

$ ./osu-winello.sh changedir /mnt/games/osu_custom

After validation, the chosen path is written to $XDG_DATA_HOME/osuconfig/osupath and exported as the OSUPATH environment variable for the current session.

How osu-winello Manages Custom Paths

The OSUPATH Variable and Configuration Storage

The script persists your custom directory choice in $XDG_DATA_HOME/osuconfig/osupath, a runtime configuration file that stores the absolute path to your osu! installation. On subsequent launches, the wrapper reads this file to determine where the game resides.

You can verify or manually edit this location by checking the configuration file, or you can override it temporarily by exporting OSUPATH before running the launcher:

$ export OSUPATH=/custom/path/to/osu
$ osu-wine

Wine Drive Mapping and longPathsFix

Once the path is stored, osu-winello must ensure Wine can access the directory as a Windows drive. The longPathsFix routine in [osu-winello.sh](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh#L410-L423) handles this by:

1. Creating a d: drive symlink inside the Wine prefix pointing to your custom directory
2. Updating the pressure-vessel mount table to expose the folder to the Wine environment

This allows the game to reference files using standard Windows path conventions (e.g., D:\Songs\) regardless of the actual Linux filesystem location.

Moving an Existing Installation

You can relocate your osu! installation at any time by re-running the directory change workflow. The script will prompt for confirmation before removing the old folder reference and updating the Wine drive mappings.

# Move installation to a new drive

$ ./osu-winello.sh changedir /new/storage/osu

# Or use the launcher shortcut if osu! is already installed

$ osu-wine --changedir

After executing the command, the InitialOsuInstall function (lines 26-44 in osu-winello.sh) proceeds normally, copying the osu!.exe binary into your newly selected directory while preserving your existing game data if present.

Summary

• Trigger custom installation with ./osu-winello.sh changedir to invoke the installOrChangeDir function (lines 63-89)
• Store the path in $XDG_DATA_HOME/osuconfig/osupath and export it as OSUPATH for the session
• Map the directory to Wine's d: drive using the longPathsFix routine (lines 410-423)
• Relocate anytime by re-running the changedir command or using osu-wine --changedir
• Launch normally with osu-wine after configuration; the script reads the saved path automatically

Frequently Asked Questions

How do I check which directory osu-winello is currently using?

Examine the contents of $XDG_DATA_HOME/osuconfig/osupath. This file contains the absolute path to your active installation directory. If the file is missing, osu-winello defaults to $XDG_DATA_HOME/osu-wine.

Can I use a path on a different partition or external drive?

Yes. The longPathsFix routine creates the necessary Wine symlinks and mount bindings regardless of the underlying filesystem location. Simply provide the mount point (e.g., /mnt/external/osu) when running the changedir command.

What happens to my existing songs and skins when I change directories?

If the new directory already contains an osu! folder with game data, the script preserves your files. When switching directories, the installer only updates the path configuration and Wine drive mappings; it does not delete your beatmaps or skins unless you explicitly remove the old folder manually.

Is there a way to set the custom directory without running the interactive installer?

Yes. You can manually create the configuration file at $XDG_DATA_HOME/osuconfig/osupath containing a single line with your desired path, or export OSUPATH as an environment variable before launching. However, running ./osu-winello.sh changedir /your/path is recommended to ensure the d: drive symlink and pressure-vessel mounts are configured correctly.

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