Simple StarCraft 2 Python Bot Template To Get Started

If you’ve ever watched an episode of ProBots and thought, “I’d love to build a bot, but where do I even start?” then you’re in the right place. We’ve created an easy-to-use python bot template that will help you dive right into StarCraft 2 bot development.

While this template alone won’t take you to the finals, it’s the perfect launchpad to get you building, testing, and learning how to program a competitive StarCraft 2 bot.

Step 1: Setup Environment

Here are a few things you’ll need to set up before getting started:

Prerequisites

Python 3.8 or newer
Git
StarCraft II (Battle.net install for Windows, Lutris/Wine for Linux)
Maps: Download the ‘Melee’ pack and put them in your StarCraft II Maps folder.
- If you use a non-standard install location, just set the MAP_PATH in config.py.

Linux with Lutris?

Set these environment variables for best results (replace paths as needed):

export SC2PF=WineLinux
export SC2PATH="/home/YOUR_USERNAME/Games/battlenet/drive_c/Program Files (x86)/StarCraft II/"
export WINE="/home/YOUR_USERNAME/.local/share/lutris/runners/wine/YOUR_WINE_VERSION/bin/wine"

Step 2: Set Up Your Bot

Head over to our GitHub page and grab the bot template.

Create a New Repository

On GitHub, click the green Use this template button (make sure you’re logged in) to create a personal copy of this bot repository.

Clone Your Repository

Open a terminal or PowerShell window, and clone your new repo:

Copy



git clone <your_git_clone_repo_url_here>

cd <bot_folder_name_here>

Create a Virtual Environment

To keep dependencies organized, set up a virtual environment:

Copy



python -m venv venv

Activate it:

Copy



venv\Scripts\activate # Windows

source venv/bin/activate # MacOS/Linux

Install Requirements

Now, install the bot’s required Python libraries:

Copy



pip install -r requirements.txt

Test Your Bot

Run your bot to check everything is working:

Copy



python run.py

If everything is set up correctly, StarCraft 2 will open, and you’ll see your bot starting to mine minerals. You can close the SC2 window to stop your bot.

Step 3: Customizing Your Bot

Naming & Race Selection

Open config.py to specify your bot’s name and race (Terran, Zerg, Protoss, or Random), choose maps, and set opponent difficulty and race.

Adding Code

Put any new files or code modifications in the bot folder. This structure is used when creating your bot’s zip file for ladder submission.

Step 4: Competing with Your Bot

When you’re ready to compete, zip up your bot for distribution. Use the following command:

Copy



python create_ladder_zip.py

This will create a bot.zip file in the publish folder. You can upload this file to ProBots competitions or the AI Arena Ladder.

Upgrade Path: Ares Framework

Want more advanced strategy and control? Upgrade to Ares-sc2 with one command:

Copy



python upgrade_to_ares.py

You’ll need to update your bot class and use super() calls in your hooks. Full guide in the repo README.

FAQs

How do I fix ‘Map not found’ or set my StarCraft II map path in Python?

If you get errors like ‘Map not found’ or trouble with map file paths, here’s what usually works:

Put your .SC2Map files in C:/Program Files (x86)/StarCraft II/Maps (no subfolders).

If you have a different SC2 setup set the map folder path in your config.py file using forward slashes. For example: MAPS_PATH = “D:/StarCraft II/Maps”

Make sure your code refers to maps by name only, e.g., “Simple64” not “Simple64.SC2Map”.

Double check there are no typos or hidden spaces. Most mapping errors come from path formatting or file location.

Error: No module named '_____' when running your bot

This error means Python can’t find the package it needs—usually because it hasn’t been installed yet. Here’s how to fix it:

Open your terminal (or command prompt) in your bot’s folder.

Run:

pip install -r requirements.txt

This will install all required dependencies for your bot, including the missing package.
If the error persists, make sure you’re using the correct Python environment (sometimes people have multiple versions or virtual environments).

I’m stuck—why can’t I get XYZ to work?

If you’re hitting a wall and nothing seems to work, you’re not alone—almost everyone gets tripped up by something odd or unexpected in setup. Often, you can get unstuck just by plugging your code or error message into ChatGPT or using an AI code editor like Windsurf that has context on your environment. These tools can spot typos, missing files, or setup quirks faster than searching forums or guessing.