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

> Learn to install osu! anywhere on Linux with osu-winello. Use the changedir command to set custom installation directories and update Wine symlinks effortlessly.

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

---

**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)](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.

```bash

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

```bash
$ 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)](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.

```bash

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