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: Bronze
Latest Wine Version Tested: 7.0-rc2

Maintainers: About Maintainership

No maintainers. Volunteer today!

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
ShowVoid LinuxJan 02 20227.0-rc2Yes Yes NoBronzeBob 
ShowUbuntu 20.04 "Focal" (+ variants like Kubuntu)Sep 26 20216.0.1Yes No NoGarbageAndrew 
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 

Known Bugs

Bug # Description Status Resolution Other apps affected

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


Comments Disabled

Comments for this application have been disabled because there are no maintainers.