Skip to content

Installation Guide

This guide will walk you through installing and setting up Balatrobot.

Prerequisites

Before installing Balatrobot, ensure you have:

  • balatro: Steam version (>= 1.0.1)
  • git: for cloning the repository
  • uv: for managing Python installations, environments and dependencies
  • lovely: for injecting Lua code into Balatro (>= 0.8.0)
  • steamodded: for loading and injecting mods (>=1.0.0)

Step 1: Install Balatrobot

Balatrobot is installed like any other Steamodded mod.

cd %AppData%/Balatro
mkdir -p Mods
cd Mods
git clone https://github.com/S1M0N38/balatrobot.git

cd "/Users/$USER/Library/Application Support/Balatro"
mkdir -p Mods
cd Mods
git clone https://github.com/S1M0N38/balatrobot.git

cd ~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro
mkdir -p Mods
cd Mods
git clone https://github.com/S1M0N38/balatrobot.git

Tip

You can also clone the repository somewhere else and then provide a symlink to the balatrobot directory in the Mods directory.

# Clone repository to a custom location
cd C:\your\custom\path
git clone https://github.com/S1M0N38/balatrobot.git

# Create symlink in Mods directory
cd %AppData%/Balatro/Mods
mklink /D balatrobot C:\your\custom\path\balatrobot

# Clone repository to a custom location
cd /your/custom/path
git clone https://github.com/S1M0N38/balatrobot.git

# Create symlink in Mods directory
cd "/Users/$USER/Library/Application Support/Balatro/Mods"
ln -s /your/custom/path/balatrobot balatrobot

# Clone repository to a custom location
cd /your/custom/path
git clone https://github.com/S1M0N38/balatrobot.git

# Create symlink in Mods directory
cd ~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods
ln -s /your/custom/path/balatrobot balatrobot
Update Balatrobot

Updating Balatrobot is as simple as pulling the latest changes from the repository.

cd %AppData%/Balatro/Mods/balatrobot
git pull

cd "/Users/$USER/Library/Application Support/Balatro/Mods/balatrobot"
git pull

cd ~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods/balatrobot
git pull
Uninstall Balatrobot

Simply delete the balatrobot mod directory.

cd %AppData%/Balatro/Mods
rmdir /S /Q balatrobot

cd "/Users/$USER/Library/Application Support/Balatro/Mods"
rm -rf balatrobot

cd ~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods
rm -rf balatrobot

Step 2: Setup Python Environment

Uv takes care of managing Python installations, virtual environments creation and dependencies installation. To setup the Python environment for running Balatrobot bots simply run:

cd %AppData%/Balatro/Mods/balatrobot
uv sync

cd "/Users/$USER/Library/Application Support/Balatro/Mods/balatrobot"
uv sync

cd ~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods/balatrobot
uv sync

The same command can be used to update the Python environment and dependencies in the future.

Remove Python Environment

To uninstall the Python environment and dependencies, simply remove the .venv directory.

cd %AppData%/Balatro/Mods/balatrobot
rmdir /S /Q .venv

cd "/Users/$USER/Library/Application Support/Balatro/Mods/balatrobot"
rm -rf .venv

cd ~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods/balatrobot
rm -rf .venv

Step 3: Test Installation

Launch Balatro with Mods

  1. Start Balatro through Steam
  2. In the main menu, click "Mods"
  3. Verify "Balatrobot" appears in the mod list
  4. Enable the mod if it's not already enabled and restart the game

macOS Steam Client Issue

On macOS, you cannot start Balatro through the Steam App due to a bug in the Steam client. Instead, you must use the run_lovely_macos.sh script.

cd "/Users/$USER/Library/Application Support/Steam/steamapps/common/Balatro"
./run_lovely_macos.sh

First-time setup: If this is your first time running the script, macOS Security & Privacy settings will prevent it from executing. Open System Preferences → Security & Privacy and click "Allow" when prompted, then run the script again.

Quick Test with Example Bot

With Balatro running and the mod enabled, you can quickly test if everything is set up correctly using the provided example bot.

cd %AppData%/Balatro/Mods/balatrobot
uv run bots/example.py

cd "/Users/$USER/Library/Application Support/Balatro/Mods/balatrobot"
uv run bots/example.py

cd ~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods/balatrobot
uv run bots/example.py

Tip

You can also navigate to the balatrobot directory, activate the Python environment and run the bot with python bots/example.py if you prefer. However, remember to always activate the virtual environment first.

The bot is working correctly if:

  1. Game starts automatically
  2. Cards are played/discarded automatically
  3. Win the first round
  4. Game progresses through rounds

Troubleshooting

If you encounter issues during installation or testing:

Once installation is complete, proceed to the Bot Development Guide to create your first bot!