# How to Fix Common Installation Issues in osu-winello: Complete Troubleshooting Guide

> Troubleshoot and fix common osu-winello installation issues. Resolve root, dependency, and network problems easily with this guide.

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

---

**Most osu-winello installation failures stem from running as root, missing system dependencies, or network connectivity issues, all of which can be resolved by running the installer as a regular user with proper packages installed and an active internet connection.**

osu-winello is a single-file Bash installer that automates running osu! on Linux through Wine. If you encounter errors during setup, understanding the installer's modular architecture and error-handling mechanisms will help you fix common installation issues in osu-winello quickly without starting from scratch.

## Understanding the osu-winello Installation Architecture

The installer ([`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh)) is a procedural Bash script organized into distinct phases. Each phase is encapsulated in a function that can be invoked independently, making targeted troubleshooting possible.

| Phase | Function Name | Line Range | Purpose |
|-------|--------------|------------|---------|
| **Initial Setup** | `InitialSetup` | 211-240 | Validates user permissions, checks for required dependencies, verifies network connectivity, and configures `$BINDIR` in `$PATH`. |
| **Wine Installation** | `InstallWine` | 73-120 | Installs the `osu-wine` launcher, downloads patched Wine-osu binaries, and sets up the `yawl` wrapper. |
| **Full Install** | `FullInstall` | 46-91 | Creates the Wineprefix scaffolding, configures registry settings, installs the osu! executable, and finalizes desktop integration. |
| **Error Handling** | `InstallError` | 134-140 | Centralized rollback function that cleans up partial installations when a critical step fails. |

When any step fails, the script calls `InstallError`, which attempts to revert changes made during the current phase. This prevents broken half-installations but means you must address the root cause before retrying.

## Common Installation Errors and Solutions

### "Please run the script without root"

**Symptom:** The installer immediately exits with a root user warning.

**Root Cause:** The `InitialSetup` function explicitly checks `if [ "$USER" = "root" ]` and triggers `InstallError` because osu-winello installs all files under `$HOME/.local/`, which should be user-owned.

**Solution:** Run the installer as a normal user:

```bash
sudo -k  # Drop root privileges if you were root

cd ~/Downloads/osu-winello
./osu-winello.sh

```

### Missing Dependencies (git, zenity, wget, unzip, realpath, pgrep)

**Symptom:** Error messages indicating commands not found during `InitialSetup`.

**Root Cause:** The script defines a dependency array `deps=(pgrep realpath wget zenity unzip)` and loops through it to verify each binary exists. If any are missing, it calls `InstallError`.

**Solution:** Install the required packages for your distribution:

**Debian/Ubuntu:**

```bash
sudo apt update
sudo apt install -y git wget unzip zenity coreutils procps

```

**Arch Linux:**

```bash
sudo pacman -S git wget unzip zenity coreutils procps-ng

```

**Fedora:**

```bash
sudo dnf install -y git wget unzip zenity coreutils procps-ng

```

### Network Connectivity Failures

**Symptom:** "Please connect to internet before continuing" despite having internet access.

**Root Cause:** `InitialSetup` pings `1.1.1.1` and `google.com` to verify connectivity. Strict firewalls, DNS blocks, or ICMP restrictions can cause false negatives.

**Solution:** If you are certain your network is functional, bypass the checks:

```bash
./osu-winello.sh --no-deps

```

> **Warning:** This skips all dependency verification. Ensure `git`, `wget`, and other required tools are installed manually before using this flag.

### Failed to Download Wine-osu Binaries

**Symptom:** Script fails during `InstallWine` with wget/curl errors or 404s.

**Root Cause:** The `DownloadFile` function attempts to fetch the patched Wine build from external URLs. Network interruptions, proxy configurations, or upstream URL changes can break this step.

**Solution:** Manual download and placement:

1. Download the Wine-osu binary manually using a browser or alternative tool.
2. Place it in `/tmp/` with the exact filename expected by the script (check the `WINELINK` variable in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) for the current version).
3. Re-run the installer:

```bash
./osu-winello.sh

```

Alternatively, configure proxy environment variables before running:

```bash
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080
./osu-winello.sh

```

### PATH Configuration Issues

**Symptom:** `osu-wine: command not found` after successful installation.

**Root Cause:** `InitialSetup` attempts to detect your shell using `detectRunningShell()` and appends `export PATH=$BINDIR:$PATH` to `~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`. In exotic shells or certain terminal environments, auto-detection fails.

**Solution:** Manually add the binary directory to your PATH:

```bash

# Immediate fix for current terminal

export PATH="$HOME/.local/bin:$PATH"

# Permanent fix for Bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.bashrc"
source "$HOME/.bashrc"

# Permanent fix for Zsh

echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.zshrc"
source "$HOME/.zshrc"

```

### Permission Denied Errors During Updates

**Symptom:** "Permission denied" when running `./osu-winello.sh update` or modifying the prefix.

**Root Cause:** Files in `$HOME/.local/` may be owned by root if you previously ran the installer with `sudo`, or the directory permissions are incorrect. The `Update` and `reconfigurePrefix` functions check writability and fail if they cannot modify files.

**Solution:** Fix ownership of the installation directory:

```bash

# Ensure all files are owned by your user

chown -R "$USER":"$USER" "$HOME/.local"

# Specifically for the osu-winello directories

chown -R "$USER":"$USER" "$HOME/.local/share/osuconfig"
chown -R "$USER":"$USER" "$HOME/.local/bin/osu-wine"

```

### Yawl Setup Failures

**Symptom:** Errors related to `yawl` (Wine wrapper) not executing or missing.

**Root Cause:** The `installYawl` function downloads and installs the `yawl` binary to `$HOME/.local/share/osuconfig/yawl` and attempts to set executable permissions with `chmod +x`. If the download failed silently or permissions weren't set correctly, the wrapper won't work.

**Solution:** Use the built-in repair command or fix manually:

```bash

# Built-in repair

./osu-winello.sh fixyawl

# Manual verification and repair

ls -l "$HOME/.local/share/osuconfig/yawl"
chmod +x "$HOME/.local/share/osuconfig/yawl"

# Re-run yawl setup if needed

YAWL_VERBS="make_wrapper=winello;exec=$HOME/.local/share/osuconfig/wine-osu/bin/wine;wineserver=$HOME/.local/share/osuconfig/wine-osu/bin/wineserver" "$HOME/.local/share/osuconfig/yawl"

```

## Advanced Troubleshooting Techniques

### Re-running Specific Installation Functions

Because [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) is structured with modular Bash functions, you can source the script and invoke specific phases without re-running the entire installer.

```bash

# Source the script to load all functions

source ./osu-winello.sh

# Re-run only the Wine installation phase

InstallWine

# Re-run the full install (skips already completed steps)

FullInstall

# Update only the launcher

Update

```

This approach is useful when a specific download fails (e.g., Wine binaries) but the initial setup completed successfully.

### Bypassing Internet Checks

For offline installations or when network checks produce false negatives, use the `--no-deps` flag:

```bash
./osu-winello.sh --no-deps

```

**Important considerations:**
- You must manually install all dependencies (`git`, `wget`, `unzip`, `zenity`, `realpath`, `pgrep`) beforehand.
- You must manually download the Wine-osu binaries and place them in `/tmp/` with the expected filenames before running.
- This flag skips the `InitialSetup` network ping tests entirely.

### Manual Binary Installation

When automated downloads consistently fail due to proxies or network restrictions:

1. Identify the required binary URLs by examining the `WINELINK` and related variables in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) (around lines 73-120 in the `InstallWine` function).
2. Download the files using a browser or alternative tool to `/tmp/`.
3. Ensure the filenames match exactly what the script expects (e.g., `wine-osu.tar.xz`).
4. Run the installer normally; it will detect existing files in `/tmp/` and skip the download step.

## Summary

- **Run as regular user:** Never execute [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) as root; the script explicitly blocks this in `InitialSetup` to maintain proper `$HOME/.local` ownership.
- **Install dependencies first:** Ensure `git`, `wget`, `unzip`, `zenity`, `realpath`, and `pgrep` are available before running the installer.
- **Verify network connectivity:** The script pings `1.1.1.1` and `google.com` during `InitialSetup`; use `--no-deps` only if you understand the implications.
- **Fix PATH issues manually:** If `osu-wine` command is not found, add `$HOME/.local/bin` to your PATH in `.bashrc` or `.zshrc`.
- **Use modular functions:** Source the script and run specific functions like `InstallWine` or `fixyawl` to repair partial installations without starting over.
- **Maintain proper permissions:** Run `chown -R "$USER":"$USER" "$HOME/.local"` if you previously used sudo or encounter permission denied errors.

## Frequently Asked Questions

### Why does the installer refuse to run when I use sudo?

The `InitialSetup` function in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) (lines 211-240) explicitly checks if `$USER` equals "root" and calls `InstallError` if true. This prevents permission conflicts because osu-winello installs all files under `$HOME/.local/`, which should be owned by your regular user account. Running as root would create files that your user cannot modify later, breaking updates and Wineprefix operations.

### Can I install osu-winello without an internet connection?

Yes, but you must use the `--no-deps` flag and manually prepare all required components. First, install the system dependencies (`git`, `wget`, `unzip`, `zenity`, `realpath`, `pgrep`) using your distribution's package manager. Then download the Wine-osu binaries and any other required files manually, placing them in `/tmp/` with the exact filenames expected by the `InstallWine` function (check the `WINELINK` variable in the script). Finally, run `./osu-winello.sh --no-deps` to skip network verification.

### What should I do if the `osu-wine` command is not found after installation?

This occurs when the `InitialSetup` function fails to automatically add `$BINDIR` (typically `$HOME/.local/bin`) to your shell's PATH, often due to exotic shell detection failures in the `detectRunningShell()` function. To fix this immediately, run `export PATH="$HOME/.local/bin:$PATH"` in your current terminal. For a permanent fix, add that line to your shell's configuration file (`~/.bashrc` for Bash, `~/.zshrc` for Zsh, or `~/.config/fish/config.fish` for Fish), then reload with `source ~/.bashrc` (or the appropriate file).

### How do I repair a partial installation if the Wine download fails but everything else works?

Because [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) is structured with modular Bash functions, you can source the script and re-run specific phases without repeating the entire installation process. First, ensure you have resolved the network issue or manually placed the Wine binary in `/tmp/`. Then execute:

```bash
source ./osu-winello.sh
InstallWine

```

This invokes only the `InstallWine` function (lines 73-120 in the source), which handles the Wine-osu binary installation and `yawl` setup. If the function detects existing files, it skips redundant steps, making this approach safe for repairing partial installations.