Poke-env: Python Interface for Pokemon Showdown Bots

poke-env is a Python library for building scripted agents, self-play experiments, and reinforcement learning workflows on Pokemon Showdown.

A simple agent in action

Installation

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

First local battle

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 and examples

Documentation, detailed examples, and starting code are available on Read the Docs.

Useful entry points:

Projects using `poke-env`

Jaxcalibur is a self-play reinforcement learning bot that reached #1 on the Generation 9 Random Battle ladder.
Pokémon Team uses the poke-env teambuilding algorithm to generate Pokémon Showdown teams from Smogon usage statistics.
Algorithmic Pokémon Teambuilding explores team optimization using simulated battles and statistical models.

Development version

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/.

Acknowledgements

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

Data files are adapted versions of the js data files from Pokemon Showdown.

License

Citing `poke-env`

@misc{poke_env,
    author       = {Haris Sahovic},
    title        = {Poke-env: pokemon AI in python},
    url          = {https://github.com/hsahovic/poke-env}
}

poke-env