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

> Boost osu-winello performance by configuring environment variables. Eliminate input lag and stuttering by setting WINEFSYNC and WINEESYNC for a smoother gaming experience.

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

---

**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`](https://github.com/nellokudo/osu-winello/blob/main/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`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) to ensure compatibility with older kernels that lack fsync/esync support. The [`stuff/winello-default.cfg`](https://github.com/nellokudo/osu-winello/blob/main/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`](https://github.com/nellokudo/osu-winello/blob/main/stuff/winello-default.cfg) – Performance defaults copied on first run
- [`stuff/example.cfg`](https://github.com/nellokudo/osu-winello/blob/main/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:

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

2. Uncomment or add the sync variables:

   ```bash
   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`](https://github.com/nellokudo/osu-winello/blob/main/example.cfg) to [`custom.cfg`](https://github.com/nellokudo/osu-winello/blob/main/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:

```bash
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:

```bash
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`](https://github.com/nellokudo/osu-winello/blob/main/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`](https://github.com/nellokudo/osu-winello/blob/main/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`](https://github.com/nellokudo/osu-winello/blob/main/winello-default.cfg) and [`example.cfg`](https://github.com/nellokudo/osu-winello/blob/main/example.cfg) from the repository's `stuff/` directory, restoring the original safe defaults and performance recommendations.