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

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

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

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.

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

Source: folderFixSetup path conversion

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.

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

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.

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

Running the Integration

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

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:

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

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

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

Source: folderFixSetup registry add

Summary

• osu-winello bridges native Linux file managers with the Wine-based osu! client through the folderFixSetup function in 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.

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