Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


ci License Package Last commit

A Python 🐍 command line tool to retrieve game server lists for various games.


  • create/update lists of game servers stored as JSON
  • removal of servers not seen in a configurable timespan
  • search game server's query ports if not contained in server list
  • handle completely broken pagination on Battlelog
  • proxy support for requests to Battlelog


You can easily install GameserverLister via pip.

pip install GameserverLister

Upgrading from an older version is equally simple.

pip install --upgrade GameserverLister

After installing through pip, you can get some help for the command line options through

$ python3 -m GameserverLister --help
Usage: python -m GameserverLister [OPTIONS] COMMAND [ARGS]...

  --help  Show this message and exit.


Required tools

The server list retrieval for GameSpy-games requires an external tool. In order to retrieve GameSpy servers, you need to set up gslist. gslist was developed by Luigi Auriemma.

Supported games

The scripts support retrieval for following games from the listed sources. If you know more sources for any of the listed games or know other games that support the listed protocols, please create an issue, and I will add them.

Game Source type/protocol Server list source(s)
7 Days to Die Valve Valve ¹
America's Army: Proving Grounds Valve Valve ¹
ARK: Survival Evolved Valve Valve ¹
Arma 2 Valve Valve ¹
Arma 3 Valve Valve ¹
Battlefield 1942 GameSpy,,
Battlefield Vietnam GameSpy,
Battlefield 2 GamsSpy,
Battlefield 2142 GameSpy,,
Battlefield: Bad Company 2 fesl/theater Electronic Arts
Battlefield 3 Battlelog
Battlefield 4 Battlelog
Battlefield Hardline Battlelog
Battlefield 1 Gametools API
Battlefield 5 Gametools API
Call of Duty Quake3 Activision
Call of Duty: United Offensive Quake3 Activision
Call of Duty 2 Quake3 Activision
Call of Duty 4: Modern Warfare Quake3 Activision
CoD4x Mod Quake3
Counter Strike Valve Valve ¹
Counter Strike: Condition Zero Valve Valve ¹
Counter Strike: Source Valve Valve ¹
Counter Strike: Global Offensive Valve Valve ¹
Crysis GameSpy
Crysis Wars GameSpy
Day of Defeat Valve Valve ¹
Day of Defeat: Source Valve Valve ¹
DayZ Valve Valve ¹
DayZ (Arma 2 mod) Valve Valve ¹
Deus Ex GameSpy,,,
Duke Nukem Forever GameSpy
Forgotten Hope 2 GameSpy
Garry's Mod Valve Valve ¹
Insurgency Valve Valve ¹
Insurgency: Sandstorm Valve Valve ¹
James Bond 007: Nightfire GameSpy,
Left 4 Dead Valve Valve ¹
Left 4 Dead 2 Valve Valve ¹
Medal of Honor Warfighter Battlelog
Nexuiz Quake3
OpenArena Quake3
ParaWorld GameSpy
Postal 2 GameSpy
Q3Rally Quake3
Quake Quake3
Quake 3 Arena Quake3,,,,,,
Return to Castle Wolfenstein Quake3 id Software
Rising Storm 2: Vietnam Valve Valve ¹
Rune GameSpy,,,
Rust Valve Valve ¹
Serious Sam: The First Encounter GameSpy,,,
Serious Sam: Second Encounter GameSpy,,,
Soldier of Fortune II: Double Helix Quake3 Raven Software
Squad Valve Valve ¹
Star Wars Jedi Knight II: Jedi Outcast Quake3 Raven Software,
Star Wars Jedi Knight: Jedi Academy Quake3 Raven Software,
SWAT 4 GameSpy
Team Fortress Classic Valve Valve ¹
Team Fortress 2 Valve Valve ¹
Tremulous Quake3
Unreal GameSpy,,,,
Unreal Tournament GameSpy,,,,
Unreal Tournament 2003 Unreal2
Unreal Tournament 2004 Unreal2,,
Unreal Tournament 3 GameSpy
UrbanTerror Quake3 FrozenSand
Vietcong GameSpy,,
Vietcong 2 GameSpy
Warfork Quake3
Warsow Quake3
Wheel of Time GameSpy,,,
Wolfenstein: Enemy Territory Quake3 id Software,
Xonotic Quake3,

¹ Valve's principal servers are rate limited. If you do not use additional filters to only retrieve matching servers, you will get blocked/timed out. You can pass filters via the -f/--filter argument, e.g. use -f "\dedicated\1\password\0\empty\1\full\1" to only retrieve dedicated servers without a password which are neither full nor empty. You can find a full list of filter options here (the \appid\ filter is applied automatically).

Game server query ports

After obtaining a server list, you may want request current details directly from the game server via different query protocols. However, only the GameSpy and Quake3 principal servers return the game server's query port. Battlelog and the EA fesl/theater do not provide details about the server's query port. So, the respective scripts attempt to find the query port if run with the --find-query-port flag.