Skip to main content

balala

PyPI CI License: GPL-3.0-or-later Python 3.9+ macOS | Windows | Linux

One command for modded Balatro.

balala installs lovely and Steamodded, plus Amulet, the maintained Talisman successor that big mods such as Cryptid expect. It installs mods from a link, keeps everything updated, and launches the game.

$ balala
First run: setting up lovely, Steamodded and Amulet.
  + lovely  v0.10.0
  + smods   main@6916f1e
  + amulet  main@9c952a2
▶ Balatro is starting with lovely v0.10.0 and 2 mods. Logs: balala logs -f

$ balala install SpectralPack/Cryptid
  + Cryptid  main@cdb0ddc

$ balala update
  ✓ lovely   v0.10.0
  ↑ smods    main@6916f1e → 1a2b3c4
  ✓ amulet   main@9c952a2
  ✓ Cryptid  main@cdb0ddc

Install

You need Balatro from Steam, Python 3.9 or newer, and git.

uv tool install balala
# or
pipx install balala

balala is one file with no dependencies, so you can also download balala.py from the latest release and run python3 balala.py.

balala update keeps balala itself current too, through whichever of these you used. A git checkout is left for you to update.

Usage

Command
balala Launch Balatro with your mods. The first time, this runs setup.
balala setup [-l|-s] Install lovely, Steamodded and Amulet.
balala install MOD... [-l|-s] [-n NAME] Install mods by name or link. Installing a mod that's already there updates it.
balala update [-l|-s] Update lovely, Steamodded, Amulet, every mod (including ones you installed by hand), and balala itself.
balala list Show what's installed.
balala remove NAME... Remove mods.
balala logs [-f] [-n N] Show the game's latest lovely log; -f follows it as the game runs.

install takes:

  • a mod's name, like Cryptid, looked up on Thunderstore and GitHub;
  • a GitHub repo: SpectralPack/Cryptid, https://github.com/SpectralPack/Cryptid, or a branch link like https://github.com/owner/repo/tree/dev;
  • any other git URL, such as a GitLab or Codeberg repo;
  • a .zip/.tar.gz link, such as a release asset;
  • a local archive or git checkout.

Each mod gets its own folder in Mods/, named after the repo. -n picks another name. After an install, balala reads the mod's Steamodded metadata and warns about dependencies that aren't installed. After any change, it warns about mods Steamodded won't load together: the same mod twice, or a mod next to one that replaces it, like Talisman next to Amulet.

Mods you installed by hand

balala takes over mods that were already in your Mods folder, so list shows them and update keeps them current. It works out where each one came from:

  • a git clone, from its remote;
  • Steamodded, from its layout;
  • anything else, from the mod's own metadata (such as a Thunderstore manifest's link), Thunderstore's Balatro catalog, or a GitHub search for the mod's id. A match counts only if that repo declares the same Steamodded id, so a different mod with the same name is never mistaken for yours.

A hand install that looks like a release (say, a Cryptid-0.5.17d folder) stays on releases; anything else tracks the newest commit. The next update replaces it with a fresh copy from its source. If you have two copies of one mod, which Steamodded won't load, balala keeps one and deletes the other. Folders it can't place, including mods with no Steamodded header, are listed and left alone.

Channels

  • -l / --latest (the default for setup and install) tracks the newest commit on the default branch, or on the branch you linked, as a shallow git clone.
  • -s / --stable installs the newest published release: the release's zip if it has one, otherwise the tag's source. A repo with no releases tracks its newest commit until it publishes one.

balala update keeps each mod on the channel it was installed with. update -l or update -s moves everything to that channel. lovely, which is compiled, and balala itself always move to their newest release.

Platforms

macOS Windows Linux
Game Steam Steam Steam, through Proton (including Steam Deck desktop mode)
lovely goes in the game folder: liblovely.dylib and run_lovely_macos.sh the game folder: winmm.dll the game folder: winmm.dll
Mods folder ~/Library/Application Support/Balatro/Mods %AppData%\Balatro\Mods …/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods
Launch lovely's script; Steam can't load lovely on macOS through Steam through Steam

balala finds the game through Steam's library list, including extra libraries on other drives.

Linux: launch Balatro once from Steam before using balala, so Proton creates its prefix. For lovely to load under Proton, Balatro's Steam launch options need WINEDLLOVERRIDES="winmm=n,b" %command%. balala adds that itself, keeping any options you already have, and backs up Steam's config (localconfig.vdf) first. Steam rewrites that file when it exits, so balala only edits it while Steam is closed and otherwise asks you to close Steam. (Balatro has no Linux build on Steam, so Steam always runs it through Proton.)

macOS has been tested end to end with the real game. On Windows and Linux, CI runs install, update and removal with real mods, and the Steam config edit is tested against sample configs, but nobody has launched the real game there yet. Reports are welcome.

What it touches

  • lovely's files in the game folder, and your Mods folder. Nothing else in the game.
  • Its own state, under ~/Library/Application Support/balala on macOS, %LocalAppData%\balala on Windows, and ~/.local/share/balala on Linux.

A mod's folder belongs to balala: update makes it match its source, and remove deletes it. The one exception is a git clone with uncommitted edits, which update leaves alone. Local commits don't stop an update, but git keeps them in git reflog for a while.

Remove Steamodded or Amulet and they stay removed (balala setup brings them back). lovely is the exception: the game can't load mods without it, so a launch reinstalls it if it's missing, after a Steam reinstall for example.

Configuration

Variable
BALALA_GAME_DIR the folder holding Balatro.app / Balatro.exe, if balala can't find it
BALALA_MODS_DIR the Mods folder
BALALA_STEAM_DIR your Steam folder, if it's somewhere unusual
BALALA_DATA_DIR where balala keeps its state
GITHUB_TOKEN raises GitHub's limit of 60 API requests an hour (gh auth token is used if you're logged in)
NO_COLOR turns off colors

The token is only ever sent to api.github.com.

Development

uv run --group dev pytest                  # everything, including tests against GitHub
uv run --group dev pytest -m "not network" # offline only
uv run --group dev ruff check && uv run --group dev ruff format --check

To release, bump __version__ in balala.py, add a CHANGELOG.md entry, and push a vX.Y.Z tag. CI builds it, makes the GitHub release, and publishes to PyPI.

Credits

Built by a9 and Claude.

lovely, Steamodded and Amulet are their authors' work. balala downloads them, and every mod, from upstream and redistributes nothing. balala isn't affiliated with LocalThunk or Playstack.

Licensed under the GNU General Public License v3.0 or later.

Metadata

Release files for balala 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for balala 1.0.0
File Size Uploaded Provenance Actions
balala-1.0.0.tar.gz 47.4 kB Without provenance Details for balala-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for balala 1.0.0
File Interpreter ABI Platform Actions
balala-1.0.0-py3-none-any.whl Python 3 none any Details for balala-1.0.0-py3-none-any.whl

Total release size: 87.0 kB

Release files / balala-1.0.0.tar.gz

Download URL balala-1.0.0.tar.gz
Size 47.4 kB
Tags Source
SHA-256 checksum
How to use checksums
367ea865eb9bdf0217cf3d16269f0851eeefa23df111bb5d5b0b4903ed5dcfce
BLAKE2b-256 checksum
How to use checksums
e5be50a8f30d4efdeda5e5c767df9966efb73f19d1ae838de4d33139021c487b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / balala-1.0.0-py3-none-any.whl

Download URL balala-1.0.0-py3-none-any.whl
Size 39.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
db0960e3eb310cc2105112c0f39e990cf528cea4f22db5321af4fd10bb16852f
BLAKE2b-256 checksum
How to use checksums
8bdd4b52f04e86fbbcb1fe3eeae5672075b9cc0248cd12800d3dfd7464aae3a6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for balala 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page