# How to Integrate Native File Managers with osu! on Wine Using osu-winello

> Integrate native Linux file managers with osu! on Wine using osu-winello. Run osu-wine --fixfolders to connect Nautilus Dolphin or Thunar to your osu! client.

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

---

**Run `osu-wine --fixfolders` to register native Linux file manager handlers that bridge Nautilus, Dolphin, or Thunar with the Wine-based osu! client.**

The osu-winello project solves the disconnect between Linux file managers and the Wine environment by implementing a registry-based bridge. The `folderFixSetup` function in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) deploys helper scripts and modifies the Wine registry to redirect folder open operations through native Linux tools, allowing seamless navigation from your desktop file manager directly into osu!'s beatmap selection dialog.

## How the Integration Works

### The folderFixSetup Function

The core logic resides in the `folderFixSetup` function inside [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh). This routine is invoked automatically when you run `osu-wine --fixfolders` or `./osu-winello.sh fixfolders`. It performs a five-step process to establish the bridge between Linux file managers and the Wine prefix.

### Helper Scripts Deployment

The routine copies two helper binaries from the repository into the user's data directory at `$XDG_DATA_HOME/osuconfig/`:

- `stuff/folderfixosu.vbs` – A Windows Script Host (WSH) script that receives a Windows-style path, converts it to a POSIX-style path, and launches `winebrowser.exe` with a `file:///` URL.
- `stuff/folderfixosu` – A compiled fallback binary that simply calls `xdg-open`.

```bash
local VBS_PATH="$XDG_DATA_HOME/osuconfig/folderfixosu.vbs"
local FALLBACK_PATH="$XDG_DATA_HOME/osuconfig/folderfixosu"
cp "${SCRDIR}/stuff/folderfixosu.vbs" "${VBS_PATH}"
cp "${SCRDIR}/stuff/folderfixosu" "${FALLBACK_PATH}"

```

*Source: [`folderFixSetup` start-up](/blob/main/osu-winello.sh#L883-L894)*

### Path Conversion and Registry Registration

The script determines the Windows-style path of the VBS script using `winepath.exe -w`. If this conversion fails, the routine automatically falls back to the compiled binary.

```bash
VBS_WINPATH="$(WINEDEBUG=-all waitWine winepath.exe -w "${VBS_PATH}" 2>/dev/null)" || fallback="1"

```

*Source: [`folderFixSetup` path conversion](/blob/main/osu-winello.sh#L996-L998)*

The script then writes to `HKEY_CLASSES_ROOT\folder\shell\open\command` in the Wine registry:

- **VBS method**: Registers `wscript.exe` with the converted Windows path to the VBS script.
- **Fallback method**: Registers the compiled binary with `xdg-open`.

```bash
waitWine reg add "HKEY_CLASSES_ROOT\folder\shell\open\command" /f /ve /t REG_SZ /d "wscript.exe \"${VBS_WINPATH//\\/\\\\}\" \"%1\""

# or fallback

waitWine reg add "HKEY_CLASSES_ROOT\folder\shell\open\command" /f /ve /t REG_SZ /d "${FALLBACK_PATH} xdg-open \"%1\""

```

*Source: [`folderFixSetup` registry write](/blob/main/osu-winello.sh#L1000-L1005)*

### File Type Associations

To handle direct beatmap file opening, the routine registers `.osu` and `.osb` extensions to a custom class `osu_winello_file`, then points that class to the same open command defined above. This enables double-clicking a beatmap folder or file in the native file manager to launch it inside the Wine instance.

```bash
waitWine reg add "HKEY_CLASSES_ROOT\.osu" /f /ve /t REG_SZ /d "osu_winello_file"
waitWine reg add "HKEY_CLASSES_ROOT\.osb" /f /ve /t REG_SZ /d "osu_winello_file"

# … then the command is added under the custom class

```

*Source: [`folderFixSetup` file-type association](/blob/main/osu-winello.sh#L1008-L1016)*

## Running the Integration

Activate the native file manager bridge by running the fix command:

```bash
osu-wine --fixfolders

# or from the repository directory:

./osu-winello.sh fixfolders

```

Verify the integration by opening your file manager (Nautilus, Dolphin, Thunar, etc.), navigating to any folder containing osu! beatmaps, and double-clicking the folder. The action should open the folder inside osu!'s "Select beatmap" dialog rather than the native file manager.

If you reinstall osu-winello or change your Wine prefix, the registry entries may be wiped. Re-run the `--fixfolders` command to restore the handlers.

## Technical Implementation Details

The VBS helper script (`stuff/folderfixosu.vbs`) handles the critical path conversion logic:

```vbscript
winPath = WScript.Arguments(0)
If Left(winPath, 1) = """" And Right(winPath, 1) = """" Then
    winPath = Mid(winPath, 2, Len(winPath) - 2)
End If
openPath = Replace(winPath, "\", "/")
cmd = "winebrowser.exe ""file:///" & openPath
Set WshShell = CreateObject("WScript.Shell")
WshShell.Run cmd, 0, False

```

*Source: [`folderfixosu.vbs`](/blob/main/stuff/folderfixosu.vbs)*

The resulting registry entry for the folder open command follows this pattern when using the VBS method:

```reg
[HKEY_CLASSES_ROOT\folder\shell\open\command]
@="wscript.exe \"C:\\Users\\user\\.local\\share\\osuconfig\\folderfixosu.vbs\" \"%1\""

```

*Source: [`folderFixSetup` registry add](/blob/main/osu-winello.sh#L1000-L1004)*

## Summary

- **osu-winello** bridges native Linux file managers with the Wine-based osu! client through the `folderFixSetup` function in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh).
- **Run `osu-wine --fixfolders`** to deploy helper scripts and register Wine registry handlers that redirect folder open operations.
- **Two helper components** handle the translation: `folderfixosu.vbs` (Windows Script Host) for standard operations, and a compiled `folderfixosu` binary as fallback.
- **Registry modifications** target `HKEY_CLASSES_ROOT\folder\shell\open\command` and custom file classes for `.osu` and `.osb` extensions.
- **Graceful degradation** ensures the integration works even if `winepath.exe` fails, by falling back to the `xdg-open` binary.

## Frequently Asked Questions

### Which Linux file managers are compatible with this integration?

The integration works with any Linux file manager that respects the XDG MIME association system, including **Nautilus** (GNOME Files), **Dolphin** (KDE), **Thunar** (XFCE), **Nemo** (Cinnamon), and **PCManFM**. The solution modifies the Wine registry, not the Linux file manager itself, so compatibility depends on the file manager's ability to launch the registered Wine handlers.

### What happens if the VBS script fails to execute?

If `winepath.exe` cannot convert the Linux path to a Windows path, or if `wscript.exe` is unavailable, the `folderFixSetup` function automatically falls back to the compiled binary at `$XDG_DATA_HOME/osuconfig/folderfixosu`. This binary directly calls `xdg-open`, ensuring that folder operations still function even when the Windows Script Host environment is compromised or missing.

### Do I need to re-run the fix after updating osu! or Wine?

You only need to re-run `osu-wine --fixfolders` if the **Wine prefix** is reset or recreated, or if you reinstall osu-winello from scratch. Standard osu! updates within the existing prefix preserve the registry entries. However, if you delete the `~/.local/share/osuconfig` directory or the Wine prefix, you must redeploy the helper scripts and re-register the handlers.

### Can I open individual beatmap files (.osu) directly from my file manager?

Yes. The integration registers the `.osu` and `.osb` extensions to a custom class `osu_winello_file` in the Wine registry. When you double-click a beatmap file in your native file manager, the handler launches it within the Wine environment, typically opening the beatmap in osu!'s editor or direct play mode, depending on the file type and osu! configuration.