poke-env is a Python library for building scripted agents, self-play
experiments, and reinforcement learning workflows on
Pokemon Showdown.
This project requires Python >= 3.10 and access to a Pokemon Showdown server. For training and local development, running your own server is strongly recommended.
pip install poke-env
You can use smogon's server to try out your agents against humans, but having a development server is strongly recommended. In particular, it is recommended to use the --no-security flag to run a local server with most rate limiting and throttling turned off. Please refer to the docs for detailed setup instructions.
git clone https://github.com/smogon/pokemon-showdown.git
cd pokemon-showdown
npm install
cp config/config-example.js config/config.js
node pokemon-showdown start --no-security
Once your local server is running, the quickest way to verify your setup is to
run two built-in players against each other. RandomPlayer uses the default
localhost server configuration, so this script should work as-is:
import asyncio
from poke_env.player import RandomPlayer
async def main():
player_1 = RandomPlayer(max_concurrent_battles=1)
player_2 = RandomPlayer(max_concurrent_battles=1)
await player_1.battle_against(player_2, n_battles=1)
print(f"Finished battles: {player_1.n_finished_battles}")
print(f"Player 1 wins: {player_1.n_won_battles}")
if __name__ == "__main__":
asyncio.run(main())To build your own bot, subclass Player and override choose_move. The
quickstart guide walks through that step by step.
Documentation, detailed examples, and starting code are available on Read the Docs.
Useful entry points:
You can also clone the latest master version with:
git clone https://github.com/hsahovic/poke-env.git
Dependencies and development dependencies can then be installed with:
cd poke-env
uv sync --dev
Run development commands through uv run, for example uv run pytest unit_tests/.
This project is a follow-up of a group project from an artificial intelligence class at Ecole Polytechnique.
You can find the original repository here. It is partially inspired by the showdown-battle-bot project. Of course, none of these would have been possible without Pokemon Showdown.
Team data comes from Smogon forums' RMT section.
Data files are adapted versions of the js data files from
Pokemon Showdown.
@misc{poke_env,
author = {Haris Sahovic},
title = {Poke-env: pokemon AI in python},
url = {https://github.com/hsahovic/poke-env}
}