The DRM-free version of the game available at and on the GOG Galaxy client.

Application Details:

Version: GOG
License: Retail
Votes: 0
Latest Rating: Gold
Latest Wine Version Tested: 4.21-staging

Maintainers: About Maintainership

Free Download Store Page

Test Results

Old test results
The test results you have selected are very old and may not represent the current state of Wine.
Selected Test Results

What works

  • Install works (though it may give a spurious error).
  • Runs fine, although some fonts may be missing for the gamepad characters in the menu and when adjusting the volume.
  • Game plays well even on medium spec hardware (i5 laptop with Intel open-source video driver).
  • All levels and bosses work great, except the final showdown with the devil. 

    At 98% complete, you may notice, as I did, that the textures start disappearing. For example, you might not be able to see the fat bad guys with little wings that the devils picks up and aims at you. In the console, I see many errors from Cuphead that I am out of Video RAM. I'm not sure what's wrong as Cuphead is supposed to use only 512MB of Graphics RAM, but my machine has much more than that.

What does not

  • Slow framerate.
  • Controllers not recognized.
  • Wine appears to freeze when quitting.

(All of the above have workarounds).


Slow framerate workaround

Create an AppDefaults override for Cuphead.exe to disable DirectX 11:

wine reg add 'HKEY_CURRENT_USER\Software\Wine\AppDefaults\Cuphead.exe\DllOverrides' /v 'd3d11' /t 'REG_SZ' /d '' /f

 This will ensure that Cuphead falls back to DirectX 9.0c, which works great.

Using Controllers

To play Cuphead with controllers instead of the keyboard, I used This also adds SDL2's gamecontrollerdb support for recognizing and  configuring different gamepads and joysticks. Note that koku-xinput did no seem to work for newer versions of Wine, for example wine-4.9.

Koku-xinput-wine is a little bit tricky to compile, but works flawlessly once installed. Personally, I copied  mine into ~/.local/lib/ and then made a script for wine:

cd ~/.wine/drive_c/GOG\ Games/Cuphead
[ -r gamecontrollerdb.txt ] || cp ~/.local/share/gamecontrollerdb.txt
LD_PRELOAD=~/.local/lib/ wine Cuphead.exe

You probably don't need to copy gamecontrollerdb.txt. I did it because the absolute best controllers for a retro run-and-gun game like Cuphead are the SNES (Super Nintendo) controllers. I have my own homebuilt device to convert SNES to USB, so I had to have my own modified version of the gamecontrollerdb.txt.

Button Mapping

I recommend the following gamepad mapping:

  • R shoulder: Shoot
  • L shoulder: Switch Weapon
  • Bottom button (A): Jump
  • Left button (X): Dash
  • Right button (B): Ex Shoot (enhanced shot)
  • Top button (Y): Lock (stay in place)

That mapping makes it more natural to hold down fire (right trigger) while jumping and dashing to dodge the bad guys.

Wine appears to freeze when quitting

One problem, with Wine 4.0.1, that did not exist in Wine 2.x is that when exiting Cuphead, the screen doesn't get refreshed. So it looks like Wine has frozen.
A workaround is to run xrefresh, immediately after wine. I do this in my cuphead script, see above.

What was not tested


Hardware tested


  • GPU: Intel
  • Driver: open source

Additional Comments

If you don't want to hassle with the workarounds, use an older version of Wine.
The Wine 2.x series, for example, required only the koku-xinput kludge.
The framerate and freezing problems did not exist.

selected in Test Results table below
Operating systemTest dateWine versionInstalls?Runs?Used
ShowDebian GNU/Linux 10.x "Buster" x86_64Dec 15 20194.21-stagingYes Yes YesGoldB Wong 
ShowDebian 9 (Stretch)May 30 20194.9Yes Yes YesBronzeB Wong 
CurrentDebian 9 (Stretch)Jun 09 20194.0.1Yes Yes YesGoldB Wong 
ShowDebian 9 (Stretch)May 30 20194.0.1Yes Yes YesGarbageB Wong 
ShowDebian 9 (Stretch)May 30 20193.0.5Yes Yes YesSilverB Wong 

Known Bugs

Bug # Description Status Resolution Other apps affected
41053 RawInput (RegisterRawInputDevices) does not work for gamepads UNCONFIRMED View

Show all bugs

HowTo / Notes

About System Specs

Please when submit results add hardware specs like as: cpu - mount of ram - videocard and videocard driver used

Remember another versions different to vanilla wine or wine staging dont accepted by wine in submited results


The following comments are owned by whoever posted them. WineHQ is not responsible for what they say.