How to Configure Custom Launch Arguments in osu-winello: A Complete Guide

osu-winello sources all *.cfg files from ~/.local/share/osuconfig/configs/ before launching, letting you define PRE_LAUNCH_ARGS for system wrappers and POST_LAUNCH_ARGS for osu! command-line flags.

The osu-winello project by nellokudo provides a flexible configuration system that lets you inject custom launch arguments without modifying the core launcher script. By placing configuration files in a specific data directory, you can prepend performance tools or append game-specific flags that automatically apply every time you start osu!.

Understanding the Configuration Mechanism

The launcher script osu-wine automatically sources every .cfg file found in the configuration directory before executing the game. According to the source code at lines 15–16, this happens early in the script:

source "$XDG_DATA_HOME/osuconfig/configs/"*.cfg 2>/dev/null

This design allows you to export environment variables or define special launch-argument variables that control how Wine executes osu!. The system recognizes two primary variables that are processed inside the LaunchOsu() function: PRE_LAUNCH_ARGS for wrappers placed before the Wine binary, and POST_LAUNCH_ARGS for flags appended after osu!.exe.

Configuring PRE_LAUNCH_ARGS and POST_LAUNCH_ARGS

Pre-Launch Wrappers and System Tools

Set PRE_LAUNCH_ARGS to inject performance tools or GPU selectors before Wine starts. Common values include gamemoderun, mangohud, or prime-run.

In stuff/example.cfg, the repository provides a placeholder:

# PRE_LAUNCH_ARGS="gamemoderun"

Remove the comment marker and adjust the value to activate your preferred wrapper:

PRE_LAUNCH_ARGS="mangohud --dlsym"

Post-Launch osu! Arguments

Use POST_LAUNCH_ARGS to pass command-line options directly to osu!.exe, such as connecting to a custom development server or enabling debug modes.

From the default configuration in stuff/example.cfg:

# POST_LAUNCH_ARGS="-devserver gatari.pw"

Uncomment and customize with your specific server or flags:

POST_LAUNCH_ARGS="-devserver akatsuki.gg"

Configuration File Location and Structure

The launcher reads configurations from:

$XDG_DATA_HOME/osuconfig/configs  →  ~/.local/share/osuconfig/configs

Any file ending in .cfg within this directory is automatically sourced via the wildcard pattern in the main script. You can create multiple files—for example, performance.cfg and server.cfg—to organize different argument sets. The repository includes stuff/example.cfg as a reference template showing all available variables, though you should place your active configs in the data directory, not the installation folder.

Editing Configurations with the Built-in Command

Rather than navigating to the directory manually, use the launcher's convenient shortcut:

osu-wine --edit-config

This command opens all *.cfg files using your $CUSTOMEDITOR environment variable or falls back to xdg-open, allowing immediate modification of launch arguments without knowing the exact path.

How Launch Arguments Are Applied in LaunchOsu()

Inside the LaunchOsu() function in osu-wine (around lines 39–62), the script converts your configuration variables into bash arrays and constructs the final execution command:

IFS=" " read -r -a PRE_ARGS  <<<"env ${PRE_LAUNCH_ARGS}"
IFS=" " read -r -a POST_ARGS <<<"${POST_LAUNCH_ARGS}"
exec "${PRE_ARGS[@]}" "${WINE}" "${OSU_EXE[@]}" "${POST_ARGS[@]}" …

This expansion places your pre-launch wrappers first, followed by the Wine binary and osu! executable, then appends your custom post-launch flags. The IFS=" " setting ensures proper word splitting for arguments containing spaces, allowing complex wrapper chains to function correctly.

Practical Configuration Examples

Example 1: Enable MangoHud and GameMode

Create ~/.local/share/osuconfig/configs/performance.cfg:

# Performance optimizations

PRE_LAUNCH_ARGS="gamemoderun mangohud"
POST_LAUNCH_ARGS=""

Example 2: Connect to a Custom osu! Server

Create ~/.local/share/osuconfig/configs/custom-server.cfg:

# Connect to private server

PRE_LAUNCH_ARGS=""
POST_LAUNCH_ARGS="-devserver localhost"

Example 3: Combined Configuration with GPU Switching

# Full custom launch with NVIDIA Prime and MangoHud

PRE_LAUNCH_ARGS="prime-run mangohud --dlsym"
POST_LAUNCH_ARGS="-devserver myserver.com -nosongselect"

After saving any .cfg file, simply run osu-wine without arguments to apply the changes immediately.

Summary

• osu-winello sources all *.cfg files from ~/.local/share/osuconfig/configs/ before launching the game, as implemented in the main osu-wine script.
• Use PRE_LAUNCH_ARGS to insert system wrappers like gamemoderun or mangohud before the Wine binary executes.
• Use POST_LAUNCH_ARGS to append command-line flags to osu!.exe, such as -devserver for custom servers.
• The osu-wine --edit-config command provides quick access to modify these files using your preferred editor.
• Multiple configuration files can coexist in the directory; the launcher sources all of them, allowing you to separate concerns like performance tuning and network settings.

Frequently Asked Questions

Where does osu-winello store its configuration files?

The launcher stores configurations in $XDG_DATA_HOME/osuconfig/configs/, which typically resolves to ~/.local/share/osuconfig/configs/ on most Linux systems. Every file ending in .cfg in this directory is automatically sourced by the main osu-wine script (lines 15–16) before the game launches.

Can I use multiple configuration files simultaneously?

Yes. The sourcing mechanism uses a wildcard pattern (*.cfg), meaning all configuration files in the directory are loaded and merged. You can split your settings across multiple files—such as performance.cfg for mangohud settings and server.cfg for devserver arguments—to keep your setup modular and organized.

How do I temporarily disable custom launch arguments?

Either comment out the variable lines in your .cfg files by adding a # at the beginning of the line, or temporarily move the files out of the ~/.local/share/osuconfig/configs/ directory. Because the script uses source with error suppression (2>/dev/null), missing or empty configurations do not cause launch failures.

What is the difference between PRE_LAUNCH_ARGS and POST_LAUNCH_ARGS?

PRE_LAUNCH_ARGS injects commands immediately before the Wine binary executes, making it ideal for system-level wrappers like gamemoderun or GPU selectors such as prime-run. POST_LAUNCH_ARGS appends text after the osu!.exe path within the Wine command, passing arguments directly to the osu! client itself, such as server connection flags or debug options.

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