How to Configure winecfg and winetricks within osu-winello: A Complete Guide

Use the osu-wine --winecfg and osu-wine --winetricks commands to manage your Wine prefix and install Windows dependencies without manual setup.

The osu-winello project by nellokudo provides a streamlined way to run osu! on Linux through Wine, but managing the underlying Windows environment requires specific knowledge of its wrapper system. Learning how to configure winecfg and winetricks within this framework allows you to tweak graphics settings, map drives, and install runtime libraries like .NET or Visual C++ redistributables that many osu! mods require.

Understanding the Wrapper Commands

The launcher script osu-wine acts as a thin shim that intercepts special flags and forwards standard Wine operations to the correct binaries. Instead of manually setting WINEPREFIX environment variables, you invoke these helpers directly.

Launching winecfg with --winecfg

When you execute osu-wine --winecfg, the script runs the winecfg binary from the selected Wine build (stored in $WINE) against the osu! prefix. This opens the standard Wine configuration UI where you can adjust Windows version emulation, graphics settings, and drive mappings.

According to the source code in osu-wine (lines 20-22), this flag simply executes $WINE winecfg, ensuring the correct environment variables are inherited from winello-default.cfg or your user configuration.

Managing Dependencies with --winetricks

The --winetricks flag forwards all subsequent arguments to the winetricks script located at $WINETRICKS. If the binary is missing, the launcher automatically invokes the installwinetricks routine defined in osu-winello.sh (lines 28-30) to download the official script.

This mechanism is implemented in osu-wine (lines 34-36) and allows you to install DLLs, fonts, and runtime packages without leaving the terminal.

Step-by-Step Configuration Examples

Use these commands to configure your osu! Wine environment. All examples assume you have already installed osu-winello and are running them from your terminal.

Open the Wine configuration GUI to tweak graphics or Windows version settings:

osu-wine --winecfg

Install essential Windows fonts and the Visual C++ 2019 runtime required by many osu! mods:

osu-wine --winetricks corefonts vcrun2019

Install the .NET 6 Desktop runtime, which is required by the Akatsuki patcher and other third-party tools:

osu-wine --winetricks dotnetdesktop6

Force installation of packages even if winetricks thinks they are already present, while ignoring non-fatal errors:

osu-wine --winetricks --force --ignore-errors vcrun2022

Customizing Your Environment

Beyond one-off commands, you can permanently adjust how winecfg and winetricks behave by modifying configuration files or environment variables.

Modifying Configuration Files

User-specific settings belong in ~/.local/share/osuconfig/configs/example.cfg, which overrides the read-only defaults in winello-default.cfg. Never edit winello-default.cfg directly, as updates will overwrite your changes.

To automatically run winetricks commands every time you launch osu!, add this to your example.cfg:

# ~/.local/share/osuconfig/configs/example.cfg

POST_LAUNCH_ARGS="--winetricks corefonts vcrun2019"

Changing the Wine Prefix Location

By default, osu-winello uses ~/.local/share/wineprefixes/osu-wineprefix. You can override this by setting the WINEPREFIX environment variable in your example.cfg:

export WINEPREFIX=/mnt/games/osu-wineprefix

Both winecfg and winetricks will then operate on this custom location when invoked through osu-wine.

Key Implementation Files

Understanding where these features are implemented helps with troubleshooting and advanced customization.

• osu-wine (lines 20-22): Parses the --winecfg flag and executes $WINE winecfg against the active prefix.
• osu-wine (lines 34-36): Handles the --winetricks flag by forwarding arguments to $WINETRICKS.
• osu-winello.sh (lines 28-30): Implements the installwinetricks function that downloads the official winetricks script if it is missing from the system.
• stuff/example.cfg: Template for user configuration, showing how to set POST_LAUNCH_ARGS or custom WINETRICKS paths.
• stuff/winello-default.cfg: System defaults defining base environment variables like $WINE, $WINEPREFIX, and $WINETRICKS.

Summary

• Use osu-wine --winecfg to open the Wine configuration GUI for adjusting graphics, Windows version, and drive mappings.
• Use osu-wine --winetricks [package] to install Windows dependencies like fonts, Visual C++ runtimes, or .NET frameworks.
• The launcher automatically installs winetricks if missing via the installwinetricks routine in osu-winello.sh.
• Customize behavior permanently by editing ~/.local/share/osuconfig/configs/example.cfg to set POST_LAUNCH_ARGS or change WINEPREFIX.
• All operations target the specific Wine prefix at ~/.local/share/wineprefixes/osu-wineprefix unless overridden.

Frequently Asked Questions

How do I open winecfg in osu-winello?

Run the command osu-wine --winecfg in your terminal. This launches the standard Wine configuration interface using the Wine binary and prefix configured for osu!, allowing you to modify graphics settings, Windows version emulation, and drive mappings without manual environment variable setup.

Can I install .NET frameworks using winetricks in osu-winello?

Yes. Execute osu-wine --winetricks dotnetdesktop6 to install the .NET 6 Desktop runtime, or use osu-wine --winetricks dotnet48 for .NET Framework 4.8. These packages are often required by third-party osu! patchers and modding tools that depend on Windows runtime libraries.

Where is the Wine prefix stored by default?

The default Wine prefix is located at ~/.local/share/wineprefixes/osu-wineprefix. You can verify or change this location by checking the WINEPREFIX variable in ~/.local/share/osuconfig/configs/example.cfg, or override it temporarily by exporting WINEPREFIX before running osu-wine commands.

How do I customize winetricks arguments permanently?

Edit the file ~/.local/share/osuconfig/configs/example.cfg and add the line POST_LAUNCH_ARGS="--winetricks [your-packages]". For example, POST_LAUNCH_ARGS="--winetricks corefonts vcrun2019" will automatically install those packages every time you launch osu-winello. Never edit winello-default.cfg directly, as it is overwritten during updates.

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