Skip to main content

Query Source and GoldSource servers for name, map, players and more.

Project description

Python A2S

Library to query Source and GoldSource servers. Impliments Valve's Server Query Protocol. Rewrite of the python-valve module. Supports both synchronous and asyncronous applications.

Official demo application: Sourcequery


Python >=3.7, no external dependencies


pip3 install python-a2s or python3 install



  • a2s.players(address, timeout=DEFAULT_TIMEOUT, encoding=DEFAULT_ENCODING)
  • a2s.rules(address, timeout=DEFAULT_TIMEOUT, encoding=DEFAULT_ENCODING)

All functions also have an async version as of package 1.2.0 that adds an a prefix, e.g. ainfo, aplayers, arules.


  • address: Tuple[str, int] - Address of the server.
  • timeout: float - Timeout in seconds. Default: 3.0
  • encoding: str or None - String encoding, None disables string decoding. Default: utf-8

Return Values

  • info: SourceInfo or GoldSrcInfo. They are documented in the source file.
  • players: List of Player items. Also documented in the corresponding source file.
  • rules: Dictionary of key - value pairs.


  • a2s.BrokenMessageError(Exception) - General decoding error
  • a2s.BufferExhaustedError(BrokenMessageError) - Response too short
  • socket.timeout - No response (synchronous calls)
  • asyncio.exceptions.TimeoutError - No response (async calls)
  • socket.gaierror - Address resolution error
  • ConnectionRefusedError - Target port closed


Example output shown may be shortened.

>>> import a2s
>>> address = ("", 27015)
SourceInfo(protocol=17, server_name=" 24/7 Dustbowl :: Nemu's Stomping Ground", map_name='cp_dustbowl',
folder='tf', game='Team Fortress', app_id=440, player_count=31, max_players=33, bot_count=21,
server_type='d', platform='l', password_protected=False, vac_enabled=True, version='5579073',
edf=177, port=27015, steam_id=85568392920040090, stv_port=None, stv_name=None,
game_id=440, ping=0.253798684978392)

>>> a2s.players(address)
[Player(index=0, name='Brutus', score=34, duration=836.4749145507812),
 Player(index=0, name='RageQuit', score=6, duration=1080.8099365234375),
 Player(index=0, name="Screamin' Eagles", score=1, duration=439.8598327636719)]

>>> a2s.rules(address)
{'coop': '0', 'deathmatch': '1', 'decalfrequency': '10', 'metamod_version': '1.10.7-devV',
 'mp_allowNPCs': '1', 'mp_autocrosshair': '1', 'mp_autoteambalance': '0', 'mp_disable_respawn_times': '0',
 'mp_fadetoblack': '0'}


  • Some servers return inconsistent or garbage data. Filtering this out is left to the specific application, because there is no general approach to filtering that makes sense for all use cases. In most scenarios, it makes sense to at least remove players with empty names. Also the player_count value in the info query and the actual number of players returned in the player query do not always match up.

  • For some games, the query port is different from the actual connection port. The Steam server browser will show the connection port and querying that will not return an answer. There does not seem to be a general solution to this problem so far, but usually probing port numbers up to 10 higher and lower than the connection port usually leads to a response. If you're still not successful, use a network sniffer like Wireshark to monitor outgoing packets while refreshing the server popup in Steam.

  • Player counts above 255 do not work and there's no way to make them work. This is a limitation in the specification of the protocol.

Tested Games

Half-Life 2, Half-Life, Team Fortress 2, Counter-Strike: Global Offensive, Counter-Strike 1.6, ARK: Survival Evolved, Rust



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for python-a2s, version 1.2.1
Filename, size File type Python version Upload date Hashes
Filename, size python_a2s-1.2.1-py3-none-any.whl (12.8 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size python-a2s-1.2.1.tar.gz (11.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page