Skip to content

Instantly share code, notes, and snippets.

@micahlt

micahlt/CavalryOnLinux.md

Created April 18, 2026 09:30
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save micahlt/3c97f834adaf688fe18344c0f546466c to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save micahlt/3c97f834adaf688fe18344c0f546466c to your computer and use it in GitHub Desktop.
Download ZIP
Raw
CavalryOnLinux.md

CavalryOnLinux

A guide to running the Cavalry motion graphics software on Linux using Wine.

This guide has been tested exclusively on Wine 11.

Initial setup

Set up a new prefix

Create a new Wine prefix by creating a folder somewhere on your computer, preferably ~/.cavalry. Within that folder, run WINE_PREFIX=~/.cavalry winetricks which should initialize the prefix.

Install fonts and graphics improvements

In Winetricks, select "Install a Windows DLL or component", then check dxvk and click okay. After it is installed, click "Install a font" and check the corefonts option. Go through all of the font installs. Once they are complete, click "Change settings" and select the fontsmooth=rgb option. These improvements make Cavalry run much smoother.

Override DLLs

Open winecfg with WINEPREFIX=~/.cavalry winecfg

Go to the Libraries tab.

Under "New override for library," type icuuc and click Add. Do the same for icuin. Ensure they are both set to (Native, Builtin).

Install Cavalry

Run the Cavalry installer .msi file through Winetricks or through the command line.

Fix Canva sign-in

Create a new .desktop file to define the Cavalry URI protocol. With the text editor of your choice, create a new file at ~/.local/share/applications/cavalry-handler.desktop. The contents should look like the following:

[Desktop Entry]
Name=Cavalry Protocol Handler
Exec=env WINEPREFIX="/home/micahlt/.cavalry" wine "/home/micahlt/.cavalry/drive_c/Program Files/Cavalry/Cavalry.exe" "%u"
Type=Application
Terminal=false
NoDisplay=true
MimeType=x-scheme-handler/cavalry;

Then run:

update-desktop-database ~/.local/share/applications
xdg-settings set default-url-scheme-handler cavalry ~/.local/share/applications/cavalry-handler.desktop

Run the app

You should be good to run Cavalry, which you should be able to find from your system menu. Canva sign-in should work properly, and you should have GPU acceleration.

@erich-muller
Copy link
Copy Markdown

erich-muller commented Apr 23, 2026

​Hey everyone, thanks for the guide! I was having an issue on Zorin OS where following the tutorial almost worked, but after the browser redirected the auth token, it kept opening a second Cavalry window instead of completing the login on the original one. (I also tried modifying the Exec to use wine start, but that just resulted in a stack overflow loop).

Gemini helped me to find out what was happening. ​It turns out the root cause is related to the Working Directory breaking the IPC (Inter-Process Communication) between the Wine instances. When the system calls the handler, it executes from the home directory, so the second instance fails to locate the original process to pass the token and decides to open a fresh window.

​To fix this, you just need to explicitly declare the Path variable in the .desktop file and use absolute paths instead of $USER or ~/.
​Here is the .desktop configuration that finally worked perfectly for me:

[Desktop Entry]
Name=Cavalry Protocol Handler
Exec=env WINEPREFIX="/home/YOUR_USERNAME/.wine" wine "/home/YOUR_USERNAME/.wine/drive_c/Program Files/Cavalry/Cavalry.exe" "%u"
Path=/home/YOUR_USERNAME/.wine/drive_c/Program Files/Cavalry/
Type=Application
Terminal=false
NoDisplay=true
MimeType=x-scheme-handler/cavalry;

Steps to apply:
​1. Replace YOUR_USERNAME with your actual Linux user folder name.
​2. Update the database: update-desktop-database ~/.local/share/applications
3. ​Important: Kill any ghost Wine processes before testing again by running wineserver -k in the terminal, otherwise the duplicated windows issue will persist from cache.

​Hope this helps anyone stuck on the same loop!

@azacio
Copy link
Copy Markdown

azacio commented Apr 23, 2026

@erich-muller THANK YOU SO MUCH! Your solution helped me to get to a working Cavalry! I took a bit of everyone's solutions in this thread, mixed them together and finally, after SIX DAYS of trying to make Cavalry work in Linux, it works!

Notes:

  1. I took @micahlt's suggestion to delete cavalry-handler.desktop and added the Mimetype line directly into the Cavalry.desktop file. I also changed the path to Cavalry in the Exec line to "C:\\\\Program Files\\\\Cavalry\\\\Cavalry.exe" %u.
  2. As @erich-muller suggested, I added the Path= line to the .desktop file.
  3. Running xdg-settings set default-url-scheme-handler cavalry ~/.local/share/applications/wine/Programs/Cavalry.desktop didn't work for me at first, producing an "application cannot be found" error. However, I shortened it to xdg-settings set default-url-scheme-handler cavalry Cavalry.desktop which executed without error. You can also verify that the mimetype was correctly set by examining the mimeinfo.cache file in the same folder as the .desktop file.
  4. Important: I moved the Cavalry.desktop file from ~/.local/share/applications/wine/Programs to the applications folder, then ran update-desktop-database ~/.local/share/applications and the xdg-settings command. This is what seemed to finally unlock the door. Previously, the handler was being set as wine-Programs-Cavalry.desktop which seemed a bit sus to me, so I decided to simplify that by moving the file.

I should also note that. as I mentioned earlier in this thread, I'm running an atomic Linux distro (Project Bluefin). Running in Bottles didn't work, running in a container didn't work, but overlaying Wine and Winetricks worked (rpm-ostree install wine winetricks for anyone who needs that). I know it's not the preferred way to do things, but whatever. I care more about doing stuff than distro ideology. (IMO Wine really, really should be part of the Bluefin images.)

And... breathe...

@micahlt
Copy link
Copy Markdown
Author

micahlt commented Apr 23, 2026

That's great to hear! I will test this myself and assuming everything works right, I will update this gist to contain these changes for future reference. Thanks for y'all's hard work trying to get this to work!

@azacio
Copy link
Copy Markdown

azacio commented Apr 24, 2026

Although the sign-in now works and I guess Cavalry does technically work, there is a known issue with connections (e.g. connecting a shape to a Duplicator). I tried messing with a few Wine render options but it seems there's something that Wine isn't translating between the Windows and Linux instructions.

I even tried Elemental Warrior Wine (which lets Affinity work on Linux), but that had... questionable results. 😅 Things like menus appearing in the middle of the screen, and the connector lines being offset away from the mouse cursor.

@PorkingMane
Copy link
Copy Markdown

PorkingMane commented Apr 25, 2026

We really need to find a way how to fix connection issue. I tried DXVK flags, virtual desktop, different WINEs but couldn't fix it at all

@micahlt
Copy link
Copy Markdown
Author

micahlt commented Apr 26, 2026

Very likely this will be an issue for someone with actual knowledge of Cavalry's architecture to build a patch or find a workaround for it. Possible a decompilation would help? Definitely depends on what technologies Cavalry is made with.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment