# How to Use osu! Mapping Tools with osu-winello: A Complete Guide

> Easily install and launch osu Mapping Tools with osu-winello. This complete guide shows you how to use the mappingTools command for a seamless mapping experience.

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

---

**osu-winello provides a dedicated `mappingTools` command that automates the installation and launching of osu! Mapping Tools inside the Wine prefix.**

The `nellokudo/osu-winello` repository is a Linux wrapper for running osu! via Wine. It includes built-in support for the community-maintained *osu! Mapping Tools* (a suite of beatmap editing utilities), allowing mappers to access advanced editing features without leaving their Linux environment.

## What Are osu! Mapping Tools?

osu! Mapping Tools is a collection of utilities created by the mapping community to streamline beatmap creation, difficulty calculation, and metadata management. These tools typically require a Windows environment or .NET runtime, which osu-winello provides through its Wine prefix configuration.

## The mappingTools Command in osu-winello

Rather than manually configuring Wine and downloading installers, osu-winello exposes a single command that handles the entire workflow.

### How It Works Internally

When you run `osu-wine --mappingtools`, the wrapper script located at `osu-wine` (lines 312-317) intercepts the flag and forwards the request to the main installation script via `MainScript "mappingTools"`.

The core logic resides in the `mappingTools()` function within [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) (lines 825-859). This function performs several critical setup steps:

1. **Process Verification** – Ensures osu! is not currently running to prevent file locks
2. **Environment Setup** – Configures a minimal .NET runtime environment inside the Wine prefix
3. **DLL Overrides** – Disables `icu.dll` overrides to prevent crashes during tool execution
4. **Registry Configuration** – Adds the `DisableHWAcceleration` registry key for Avalon graphics to ensure UI stability
5. **Installer Management** – Downloads the official `mapping_tools_installer_x64.exe` using the URL constructed from `MAPPINGTOOLSLINK` (defined in lines 25-41) and executes it within the Wine prefix
6. **Process Integration** – Launches Mapping Tools using `yawl` with the `enter=$OSUPID` verb, ensuring it runs inside the same Wine container as osu!

### Version and Download Configuration

The script maintains version control through variables defined at lines 25-41 of [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh):

- `MAPPINGTOOLSVERSION` – Tracks the current release version
- `MAPPINGTOOLSLINK` – Constructs the direct download URL for the x64 installer

This ensures users always receive the latest stable release without manual URL hunting.

## Step-by-Step Installation and Usage

Follow these steps to run osu! Mapping Tools on Linux using osu-winello:

```bash

# 1. Install osu-winello (if not already installed)

git clone https://github.com/NelloKudo/osu-winello.git
cd osu-winello
chmod +x ./osu-winello.sh
./osu-winello.sh

# 2. Launch osu! (required before starting Mapping Tools)

osu-wine

# 3. In a separate terminal, while osu! is running, launch Mapping Tools

osu-wine --mappingtools

```

**Note:** If you have already installed osu-winello but never used Mapping Tools, simply run `osu-wine --mappingtools`. The script automatically detects missing installations, downloads the installer, and launches the tools.

During first installation, the Windows installer UI will appear within your Wine prefix. Accept the default installation prompts to complete the setup.

## Key Source Files and Functions

Understanding the source structure helps with troubleshooting:

| File | Purpose | Key Section |
|------|---------|-------------|
| [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) | Core installer and utility functions | Lines 25-41 (version/URL definition), Lines 825-859 (`mappingTools()` implementation) |
| `osu-wine` | User-facing wrapper script | Lines 312-317 (`--mappingtools` flag handling) |
| [`README.md`](https://github.com/nellokudo/osu-winello/blob/main/README.md) | Documentation | Flags section documenting `--mappingtools` usage |

## Summary

- **osu-winello** provides native Linux support for osu! Mapping Tools through the `osu-wine --mappingtools` command.
- The implementation automatically handles .NET environment setup, DLL configuration, and registry modifications required for stable operation.
- Mapping Tools run inside the same Wine prefix as osu!, ensuring seamless integration with your existing beatmap library.
- Source code locations: Version definitions in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) lines 25-41, core logic in lines 825-859, and CLI handling in `osu-wine` lines 312-317.

## Frequently Asked Questions

### Do I need to install .NET Framework manually to use Mapping Tools with osu-winello?

No. The `mappingTools()` function in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh) automatically configures a minimal .NET environment within the Wine prefix. It handles all necessary runtime dependencies, including disabling problematic `icu.dll` overrides and setting registry keys for graphics acceleration.

### Can I run Mapping Tools while osu! is closed?

No. The script explicitly checks that osu! is running before launching Mapping Tools. The implementation uses `yawl` with the `enter=$OSUPID` verb to inject the process into the same Wine container as the running osu! instance. If osu! is not active, the script will prompt you to start it first.

### Where are the Mapping Tools installed when using osu-winello?

The installer downloads `mapping_tools_installer_x64.exe` from the official GitHub releases (as defined by `MAPPINGTOOLSLINK` in lines 25-41 of [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/osu-winello.sh)) and executes it within the Wine prefix. The actual installation location follows the standard Windows installer defaults inside your osu-winello Wine prefix, typically under `drive_c/Program Files/` or the user's selected directory during the installation wizard.