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.
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 /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.
Uninstall Balatrobot
Simply delete the balatrobot mod directory.
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:
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.
Step 3: Test Installation
Launch Balatro with Mods
- Start Balatro through Steam
- In the main menu, click "Mods"
- Verify "Balatrobot" appears in the mod list
- 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.
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.
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:
- Game starts automatically
- Cards are played/discarded automatically
- Win the first round
- Game progresses through rounds
Troubleshooting
If you encounter issues during installation or testing:
- Discord Support: Join our community at https://discord.gg/xzBAj4JFVC for real-time help
- GitHub Issues: Report bugs or request features by opening an issue on GitHub
- Documentation: Check the Troubleshooting page (work in progress)
Once installation is complete, proceed to the Bot Development Guide to create your first bot!