How to Configure Environment Variables for Performance Tuning in osu-winello

Set WINEFSYNC=1 and WINEESYNC=1 in ~/.local/share/osuconfig/configs/*.cfg or export them before launching to eliminate input latency and stuttering in the Wine-based osu! runtime.

The osu-winello project by nellokudo provides a Bash-based installer and launcher for osu! stable on Linux. Because the game runs through Wine, performance depends heavily on kernel-level synchronization primitives controlled via environment variables. The main script, osu-winello.sh, exports safe defaults but allows users to override them through persistent configuration files for maximum performance.

Understanding the Performance-Critical Environment Variables

The launcher recognizes several variables that directly impact frame pacing and input latency. These are defined in the script with conservative defaults, then optionally overridden by user configuration.

Variable	Purpose	Script Default	Recommended Value
WINENTSYNC	Disables Windows event synchronization to reduce latency	0 (disabled)	0 (keep disabled)
WINEFSYNC	Enables fsync for kernel-based file-system call batching	0 (disabled)	1 (enable)
WINEESYNC	Enables esync for userspace event synchronization	0 (disabled)	1 (enable)
WINE_DISABLE_FULLSCREEN_HACK	Disables Wine's fullscreen hack to prevent compositor stutter	1 (enabled)	1 (keep enabled)
vblank_mode	Controls frame rate capping (0 = uncapped)	0 (uncapped)	0 (uncapped)
__GL_SYNC_TO_VBLANK	Synchronizes OpenGL to vertical blank	0 (disabled)	0 (disabled)

The script exports WINENTSYNC, WINEFSYNC, and WINEESYNC to 0 early in osu-winello.sh to ensure compatibility with older kernels that lack fsync/esync support. The stuff/winello-default.cfg file provides performance-oriented overrides (1 for sync features) that are copied to the user config directory on first install.

Where Configuration Files Are Stored

User-editable configurations reside in ~/.local/share/osuconfig/configs/. The installer creates this directory and populates it with files from the repository's stuff/ directory:

• stuff/winello-default.cfg – Performance defaults copied on first run
• stuff/example.cfg – Template with documentation for all variables

The launcher sources all *.cfg files in the configs directory, allowing you to maintain multiple profiles or backup configurations.

Methods to Configure Environment Variables

Permanent Configuration via Config Files (Recommended)

For persistent settings across launches, edit or create a configuration file in the user config directory.

1. Open the example configuration:

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

2. Uncomment or add the sync variables:

   WINEFSYNC=1
   WINEESYNC=1

3. Save and exit. The next invocation of osu-wine automatically sources these values.

You can create multiple profiles by copying example.cfg to custom.cfg and adjusting variables per-profile.

Temporary Session-Based Configuration

To test settings without modifying files, export variables in your current shell before launching:

export WINEFSYNC=1 WINEESYNC=1
osu-wine

This method applies only to the current terminal session and is useful for benchmarking different configurations.

Verifying Your Configuration

After modifying variables, confirm they are active by checking the launcher's environment output:

osu-wine --info | grep -E 'WINEFSYNC|WINEESYNC'

Expected output when performance tuning is enabled:

WINEFSYNC=1
WINEESYNC=1

If the output shows 0 or empty values, verify that your config file is saved in ~/.local/share/osuconfig/configs/ with a .cfg extension and that no syntax errors exist.

Summary

• Primary location: Edit ~/.local/share/osuconfig/configs/*.cfg for permanent changes to environment variables in osu-winello.
• Key variables: Set WINEFSYNC=1 and WINEESYNC=1 to enable kernel and userspace synchronization for reduced input latency.
• Safety defaults: The script osu-winello.sh exports conservative values (0) to ensure compatibility; override these via config files for performance.
• Verification: Use osu-wine --info to confirm active environment variables before launching gameplay.

Frequently Asked Questions

What is the difference between fsync and esync in osu-winello?

Fsync (WINEFSYNC) uses Linux kernel primitives (futexes) to synchronize Wine's Windows threads, reducing context switches and latency. Esync (WINEESYNC) provides a userspace fallback for systems without fsync support. According to the osu-winello source code, modern kernels should use WINEFSYNC=1 for best performance, while WINEESYNC=1 serves as a compatibility layer on older systems.

Why does osu-winello disable fsync and esync by default?

The script osu-winello.sh exports WINEFSYNC=0 and WINEESYNC=0 to ensure the launcher works on older kernels that lack the necessary syscall support. If the script forced these to 1, Wine would abort on incompatible systems. Users with modern kernels (5.16+ for fsync) must explicitly enable these features via the configuration files to unlock performance tuning benefits.

Can I use environment variables to fix screen tearing or stuttering?

Yes. The WINE_DISABLE_FULLSCREEN_HACK=1 variable prevents Wine from manipulating window decorations in ways that conflict with Linux compositors, eliminating stutters on some desktop environments. Additionally, vblank_mode=0 and __GL_SYNC_TO_VBLANK=0 disable vertical synchronization in the graphics driver, which removes frame rate caps and reduces input lag. These are all configurable in ~/.local/share/osuconfig/configs/*.cfg.

How do I reset osu-winello to default settings?

Delete or rename the user configuration directory to force the script to regenerate defaults. Run rm -rf ~/.local/share/osuconfig/configs/ and launch osu-wine again. The installer will copy fresh versions of winello-default.cfg and example.cfg from the repository's stuff/ directory, restoring the original safe defaults and performance recommendations.

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