pyrad2

A modern Python toolkit for building RADIUS clients and servers.

pyrad2 gives you the protocol - packet encoding, dictionary parsing, transport handling, retransmission, TLS - so you can write the business logic. Build an authentication backend, a CoA proxy, a RadSec accounting collector, or a network-access controller without touching wire formats.

📚 Full documentation: pyradius.github.io/pyrad2

Install

pip install pyrad2     # or: uv add pyrad2

Requires Python 3.12+.

Quick look

from pyrad2.client_async import ClientAsync
from pyrad2.dictionary import Dictionary
from pyrad2.constants import PacketType

client = ClientAsync(server="radius.example.com", secret=b"...", dict=Dictionary("dictionary"))
await client.initialize_transports(enable_auth=True)

req = client.create_auth_packet(User_Name="alice", User_Password="hunter2")
reply = await client.send_packet(req)

if reply.code == PacketType.AccessAccept:
    print("Welcome,", reply["User-Name"][0])

Head to the Getting Started guide for the full walkthrough.

What's in the box

pyrad2 is a library, not a daemon. It is not a drop-in replacement for FreeRADIUS; it gives you the moving parts to build your own.

See it run

Two complementary surfaces ship with the repo:

• scenarios/ - single-process, end-to-end demos. A server and a client run in the same event loop so the full exchange shows up on one log. Don't edit them - they're runnable explanations.
• examples/ - operational scripts you copy into your project and edit.

make demo                  # all scenarios sequentially

make scenario_auth         # Access-Request → Access-Accept (UDP)
make scenario_acct         # Accounting-Request → Accounting-Response
make scenario_coa          # CoA-Request → CoA-ACK (RFC 5176)
make scenario_status       # Status-Server health check (RFC 5997)
make scenario_dedup        # Duplicate detection (RFC 5080)
make scenario_radsec       # RadSec over mutual TLS (RFC 6614)
make scenario_radsec_v11   # RADIUS/1.1 over RadSec (RFC 9765)
make scenario_proxy        # Client → Proxy → Upstream RADIUS server (RFC 2865 §2)
make scenario_auth_chap          # CHAP authentication (RFC 1994)
make scenario_auth_eap_md5       # EAP-MD5 (RFC 3748)
make scenario_auth_eap_gtc       # EAP-GTC (RFC 3748)
make scenario_auth_eap_mschapv2  # EAP-MSCHAPv2 (RFC 2759), needs pyrad2[mschap]

Watch the actual bytes on the wire by setting PYRAD2_TRACE=1 on any script:

PYRAD2_TRACE=1 make scenario_auth

Documentation

• Getting Started - install, RADIUS in one minute, run an exchange
• Running a Server - auth, accounting, CoA, RadSec, RADIUS/1.1
• Making Requests - clients, EAP, health checks, RadSec
• Dictionary Reference - every supported type and option
• Migrating from pyrad - breaking changes since 2.0

Tests

make test

Author, Copyright, Availability

pyrad2 is currently maintained by Nicholas Amorim.

pyrad was written by Wichert Akkerman and is maintained by Christian Giese (GIC-de) and Istvan Ruzman (Istvan91).

This project is licensed under a BSD license. Copyright and license information can be found in LICENSE.txt.

Bugs and wishes can be submitted in the pyrad2 issue tracker on GitHub. PRs are very welcome.