Install guide

How to install Balatro mods

Most Balatro mods load through two tools. Lovely is an injector that patches the game each time it starts. Steamodded (also called smods) is a mod loader that runs on top of Lovely and gives mods a shared toolkit and an in-game Mods menu. Some mods need both, some only need Lovely.

This guide sets up both, shows where the Mods folder is on each system, and covers the problems people hit most often.

What each aong.dev mod needs
Mod	Lovely	Steamodded
Edition Decks	Yes	Yes, 26.829.0 or newer
Better Background	Yes, 0.9 or newer	Optional
Chromite In development	Yes, 0.9 or newer	Optional

1 Install Lovely

Download the latest release from Lovely's GitHub releases. To open the game folder, right-click Balatro in Steam, choose Manage › Browse local files.

Windows: Download lovely-x86_64-pc-windows-msvc.zip and copy winmm.dll into the game folder. If you used an older Lovely, delete its version.dll from the game folder. Start Balatro from Steam as usual.
Steam Deck & Linux (Proton): Use the same Windows winmm.dll, then set Balatro's launch options in Steam to WINEDLLOVERRIDES="winmm=n,b" %command%.
macOS: Download the build for your Mac (aarch64 for M-series, x86_64 for Intel) and copy liblovely.dylib and run_lovely_macos.sh into the game folder. Start the game with that script, not from Steam.

Lovely's own install notes have the latest details for each system.

2 Install Steamodded

Skip this step if every mod you want lists Steamodded as optional. Otherwise, download the latest Steamodded from its GitHub releases, unzip it, and move the folder into your Mods folder (next step). The Steamodded docs have the official walkthrough.

When it's working, the main menu has a Mods button that lists everything installed.

3 Find your Mods folder

The Mods folder is in Balatro's save folder, not the game folder. If it isn't there, create a folder named Mods, or start the game once with Lovely installed and it will be made for you.

Windows: %AppData%\Balatro\Mods (paste it into the File Explorer address bar)
macOS: ~/Library/Application Support/Balatro/Mods (press Shift-Command-. in Finder to show hidden folders)
Steam Deck & Linux: ~/.steam/steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods
Flatpak Steam: ~/.var/app/com.valvesoftware.Steam/.steam/steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods

4 Add a mod

Download the mod's zip. On aong.dev that's the green Download button on each mod page.
Unzip it. You get one folder, such as EditionDecks-main.
Move that folder into the Mods folder. Each mod needs its own folder there.
Start Balatro. Mods that use Steamodded show up under Mods on the main menu.

The -main at the end of a folder downloaded from GitHub is fine to keep or remove.

Mod compatibility

aong.dev mods are built to share a Mods folder. These are the combinations we have checked and how each one behaves.

Chromite + Handy: Chromite's speed, animation skip and keys step aside for Handy's. A Force switch turns Chromite's versions on anyway.
Chromite + Saturn: Speed and animation skip step aside the same way.
Chromite + JokerDisplay: JokerDisplay stays in charge of Joker overlays. Chromite adds a key to show or hide them.
Chromite + Multiplayer: Chromite features that change pacing switch off inside lobbies.
Better Background + Chromite: Better Background switches itself off, since Chromite includes the same background features.

Troubleshooting

The Mods button doesn't appear on the main menu

Steamodded isn't loading. Check that Lovely is installed in the game folder (on Windows, a console window opens next to the game when it is), and that the Steamodded folder sits directly inside the Mods folder.

A mod is in the folder but the game ignores it

Check for a folder inside a folder, like Mods/BetterBackground/BetterBackground/. Unzipping sometimes adds an extra level. Move the inner folder up so the mod's files are one level below Mods.

The game crashes after adding a mod

Read the crash screen for the mod's name, and check that mod's page for the Lovely or Steamodded version it needs. If two mods clash, move one out of the Mods folder and start again to find which.

What's the difference between Lovely and Steamodded?

Lovely changes the game's code as it loads. Steamodded is a mod that Lovely loads, which then loads other mods and gives them shared tools and a config menu. Steamodded always needs Lovely.

How do I remove a mod?

Move its folder out of the Mods folder. To turn all mods off, remove Lovely's file from the game folder.