poke-env is the harness, and the server is your problem

There is no simulator here, only a client for someone else's

The first sentence of the README describes the library accurately: it is for building scripted agents, self-play experiments and reinforcement learning workflows on Pokemon Showdown. What it is not is stated by what the repository does not contain. There is no game engine, no battle simulator and no bundled dataset, because the simulator is Pokemon Showdown itself and the library speaks to it over the wire. Two requirements follow directly. Python 3.10 or newer, and access to a Showdown server. The README goes further and says running your own server is strongly recommended for training and local development, which is the sentence that separates a quick experiment from a usable setup. Using Smogon's public server is offered as a way to try agents against humans, and the distinction the README draws is the important one: public play is for a first look, local development is for anything you intend to iterate on. Installing the library itself is one command, pip install poke-env, and the distribution is published on PyPI under the name poke_env, with the hyphen reserved for the import statement.

The --no-security flag is what makes a local server usable

Setting up the server takes five commands and one decision that matters more than the other four. You clone the Showdown repository, change into it, install its Node dependencies, copy the example configuration to a real one, and start it. The decision is the flag: the README recommends running a local server with the no-security flag so that most rate limiting and throttling are turned off.

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

The reasoning is obvious once you understand what the library does. A training loop or a self-play experiment sends requests far faster than a human plays, and a server configured for human traffic will throttle it, which turns a throughput problem into an intermittent failure that looks like a bug in your agent. The flag is also the reason this setup belongs on a machine you control rather than a shared host, since it removes protections that exist for other people's traffic. The README points at its own documentation for detailed setup instructions, and the configuration file you copy is the place where a local username, format and room settings would live.

Two built-in random players are the smoke test

The library's own first-battle example is the fastest way to find out whether your server, your install and your event loop are wired together correctly. It creates two RandomPlayer instances, each with a concurrency of one, asks one to battle the other for a single battle, and prints how many battles finished and how many the first player won. The reason this works as written is that RandomPlayer uses the default localhost server configuration, so nothing needs configuring before the script runs:

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())

Three things are worth noting in twenty lines. Battles are counted on the player objects, so instrumentation comes from the library rather than from your own logging. Concurrency is a constructor argument, which is the knob a self-play experiment turns up. And the whole thing is asyncio, so an agent that wants to react to a message mid-battle can, rather than waiting for a turn boundary it was never given.

The extension point is one method: override choose_move

Building an actual bot takes one subclass and one override. You subclass Player and override choose_move, and the quickstart guide walks through that step by step. That is a small surface, and it is worth understanding what it implies. The library owns the protocol, the battle state and the timing, and your code answers a single question: given what has happened, what do I do now. Everything else a bot needs, such as switching on a stat comparison or reading an opponent's team, is something you write inside that method against state the library exposes. The examples directory shows how wide that becomes in practice, with separate files for connecting an agent to Showdown, custom team building, reinforcement learning, saving replays, self-play, building teams from Smogon statistics, tracking observations, and a custom team builder notebook. The team builder files matter because team construction is where most of the interesting non-combat work sits, and it is the one part of a Showdown bot that is reusable outside a battle.

gymnasium, pettingzoo and websockets are pinned to exact versions

The dependency list is where an agent project stops being flexible. The runtime dependencies are short and mostly ordinary: numpy from 2.0.2, requests from 2.32.3, tabulate, and orjson for fast parsing. Three of them are exact pins rather than ranges, and they are the three that matter. gymnasium is pinned to 1.3.0 and pettingzoo to 1.24.3, which together define the interface your environment and your multi-agent loop are written against, and websockets is pinned to 16.1.1, which defines the transport. Exact pins on an API surface and a transport library are a defensible choice and an inconvenient one: you cannot share an environment with a project on a different gymnasium version without patching one of them, and an upgrade is a deliberate act rather than a resolution. The documentation extra is separate and holds the Sphinx toolchain. Development dependencies are managed as a group for the uv workflow, with black, flake8, isort, mypy, pre-commit and pytest all pinned, and the repository additionally carries a flake8 configuration and a pre-commit configuration file.

A number one ladder bot and two team builders use it

The README lists three projects built on the library, and they show two different uses. Jaxcalibur is a self-play reinforcement learning bot that reached first place on the Generation 9 Random Battle ladder, which is the strongest evidence here that the environment is faithful enough for a learned policy to transfer to real opponents. The other two are about teams rather than play. Pokémon Team uses the teambuilding algorithm to generate Showdown teams from Smogon usage statistics, and a separate write-up explores team optimization using simulated battles and statistical models. Read together they suggest the teambuilder half of the library is the part with independent value, because a team generator does not need a ladder, an opponent or a training loop to be useful. The data behind all of this comes from Smogon, specifically the forums' competitive team discussion section, and the data files shipped in the repository are described as adapted versions of the JavaScript data files from Showdown itself rather than as original work.

Alpha at 0.16.1, with three test suites and a committed gif

Two housekeeping details are worth knowing before you build on this. The packaging metadata classifies the project as development status 3, alpha, which is a self-assessment that has not changed even as the version has moved through 0.15, 0.16.0 and 0.16.1. Release notes for those three give a sense of what changes: 0.15.0 added Pokémon Champions, a technology entry for Zoroark and custom message handlers, 0.16.0 added Smogon statistics, team generation and support for the b03 format, and 0.16.1, two days later, updated the team generation algorithm. So the recent work has been team construction and format coverage rather than the agent interface. The second detail is the test layout. There are three separate directories: unit tests, integration tests and strict integration tests, plus a fixture_data directory, a conftest file at the root and a diagnostic_tools directory. Development commands go through uv, with a sync that installs the development group and a run wrapper, and the example invocation in the README targets the unit test directory, which suggests the integration suites are run deliberately rather than by default.

Editorial conclusion

Adopt poke-env if you want your reinforcement learning environment to be the real game rather than a model of it, since the whole value of the library is that it speaks the Showdown protocol instead of reimplementing the rules. Running your own server with security checks disabled is a hard prerequisite for anything beyond a smoke test, and the smoke test itself is two built-in random players. Do not adopt it if you need a self-contained environment that starts in one command, because this is a client library and the simulator lives in a Node project you install separately. Four things to check first. Whether you can run a Showdown server locally, since the README recommends it strongly and suggests disabling rate limiting for development. Which Python you have, since the floor is 3.10 and the classifiers run to 3.14. Whether your gymnasium and pettingzoo versions match, since both are pinned to exact versions. And whether alpha classification at 0.16.1 matches your risk tolerance for an interface you will build an agent on.

Frequently asked questions

Official sources

1. hsahovic/poke-env on GitHub
2. License: MIT
3. Project website
4. README
5. Releases