Quick answer: A Python IRCd is a stateful protocol server: accept connections, parse framed IRC commands, authenticate clients, maintain users and channels, authorize actions, and broadcast validated messages. Separate protocol parsing from shared state and test floods, disconnects, and malformed input in an isolated environment.
A Python IRCd is an IRC daemon: a server process that accepts IRC clients, parses text commands, tracks nicknames and channels, and sends replies using the IRC wire format. Building a small one is a useful way to learn sockets, protocol parsing, and async server design.
The protocol references are the original RFC 1459 IRC protocol, RFC 2810 architecture, RFC 2812 client protocol, and RFC 2813 server protocol. For Python networking, use the official socket documentation and asyncio streams documentation. TLS deployment commonly uses the IRC TLS port described in RFC 7194.
This guide builds a teaching server, not a production IRC network. A real IRCd needs flood control, TLS, authentication policy, operator controls, channel modes, ban lists, services integration, monitoring, persistence, and extensive interoperability testing. The examples below stay local and offline-safe: they parse strings, use in-memory state, use socket.socketpair(), and keep the asyncio listener behind a disabled guard.
Parse IRC Messages
IRC clients send one command per line. A line can have an optional prefix, a command, middle parameters, and one final trailing parameter that may contain spaces. Start by parsing that shape before touching sockets.
from dataclasses import dataclass
@dataclass
class IrcMessage:
prefix: str | None
command: str
params: list[str]
def parse_message(line):
line = line.rstrip("\r\n")
prefix = None
if line.startswith(":"):
prefix, line = line[1:].split(" ", 1)
if " :" in line:
before, trailing = line.split(" :", 1)
parts = before.split()
parts.append(trailing)
else:
parts = line.split()
if not parts:
raise ValueError("empty IRC message")
command, *params = parts
return IrcMessage(prefix, command.upper(), params)
samples = [
"NICK ada\r\n",
"USER ada 0 * :Ada Lovelace\r\n",
":ada!u@host PRIVMSG #lab :hello from Python\r\n",
]
for sample in samples:
print(parse_message(sample))
The parser keeps bytes and networking out of the first step. That makes command handling easier to test with fixtures from client transcripts. The final parameter rule matters for commands such as USER, PRIVMSG, NOTICE, and server numerics because their human-readable text often contains spaces. IRC and Discord bots are both event-driven chat systems; Fix Discord on_message Command Issues explains why a Discord on_message handler can stop command dispatch.
Format Replies Safely
An IRC server sends text lines terminated by CRLF. RFC 2812 limits a protocol line to 512 octets including the terminator, so a small formatter should check size before returning bytes.
MAX_IRC_LINE = 512
def format_line(command, *params, prefix=None):
pieces = []
if prefix:
pieces.append(f":{prefix}")
pieces.append(command.upper())
for index, item in enumerate(params):
text = str(item)
is_last = index == len(params) - 1
needs_trailing = text == "" or text.startswith(":") or " " in text
pieces.append(f":{text}" if is_last and needs_trailing else text)
data = (" ".join(pieces) + "\r\n").encode("utf-8")
if len(data) > MAX_IRC_LINE:
raise ValueError("IRC line is too long")
return data
print(format_line("001", "ada", "Welcome to local IRCd", prefix="local.test").decode(), end="")
print(format_line("PONG", "local.test", "12345").decode(), end="")
Keep formatting in one helper rather than scattering string joins across the server. That avoids accidental missing CRLF terminators, lowercase commands, or oversized replies. It also gives tests one place to assert that command output matches the wire format.
Track Client Registration
A client is not fully registered until the server has enough identity information. A minimal teaching server can wait for NICK and USER, then send a welcome numeric. A production server has more checks, but the state transition is the same idea.
from dataclasses import dataclass, field
def numeric_reply(code, nick, text):
target = nick or "*"
return f":local.test {code} {target} :{text}\r\n".encode("utf-8")
@dataclass
class ClientState:
nick: str | None = None
user: str | None = None
registered: bool = False
outbox: list[bytes] = field(default_factory=list)
def handle_registration(state, command, params):
if command == "NICK" and params:
state.nick = params[0]
elif command == "USER" and params:
state.user = params[0]
if state.nick and state.user and not state.registered:
state.registered = True
state.outbox.append(numeric_reply("001", state.nick, "Welcome to the local Python IRCd"))
client = ClientState()
handle_registration(client, "NICK", ["ada"])
handle_registration(client, "USER", ["ada", "0", "*", "Ada Lovelace"])
print(client.registered)
print(client.outbox[0].decode(), end="")
This keeps client state explicit. Later handlers can reject channel joins or private messages from unregistered clients, and tests can verify that duplicate registration does not send the welcome reply twice. Store credentials and account policy outside this tiny state object if your design grows beyond a local lab.
Route Local Channel Messages
Channels are shared rooms. For a small single-process server, an in-memory mapping from channel names to client ids is enough to test join and message routing. The same interface can later be backed by richer membership objects.
from collections import defaultdict
channels = defaultdict(set)
nicks = {"c1": "ada", "c2": "grace", "c3": "linus"}
def join_channel(client_id, channel):
if not channel.startswith("#"):
raise ValueError("channel names should start with #")
channels[channel].add(client_id)
nick = nicks[client_id]
return [(client_id, f":{nick} JOIN {channel}\r\n".encode("utf-8"))]
def route_privmsg(sender_id, channel, text):
if sender_id not in channels[channel]:
return []
sender = nicks[sender_id]
line = f":{sender} PRIVMSG {channel} :{text}\r\n".encode("utf-8")
return [(client_id, line) for client_id in channels[channel] if client_id != sender_id]
join_channel("c1", "#python")
join_channel("c2", "#python")
join_channel("c3", "#ops")
for client_id, payload in route_privmsg("c1", "#python", "hello channel"):
print(client_id, payload.decode().strip())
The routing function returns deliveries instead of sending immediately. That separation makes tests deterministic and lets the socket layer decide whether each client can accept more bytes. It also gives you a natural place to add rate limiting, permission checks, and logging before a message leaves the server.
Test Framing Without A Network Port
You can test byte framing without opening a TCP listener. socket.socketpair() creates two connected sockets inside the current process, which is enough to verify that line-reading code waits for CRLF and enforces the size limit.
import socket
def read_irc_line(sock, limit=512):
data = bytearray()
while not data.endswith(b"\r\n"):
chunk = sock.recv(1)
if not chunk:
break
data += chunk
if len(data) > limit:
raise ValueError("IRC line is too long")
return bytes(data)
left, right = socket.socketpair()
try:
right.sendall(b"PING :local-test\r\n")
print(read_irc_line(left).decode("utf-8").strip())
finally:
left.close()
right.close()
This is a safer validation path than starting a public service during unit tests. Add cases for empty reads, lines without CRLF, oversized lines, invalid UTF-8, and command text with a trailing parameter. When framing tests are stable, socket bugs become much easier to isolate.
Add A Guarded asyncio Server
When the parser and handlers are covered by offline tests, wire them into an async server. Bind to 127.0.0.1 while developing and use port 0 to let the operating system choose a free loopback port. Keep the launch behind an explicit guard so importing the module never starts a listener.
import asyncio
async def handle_client(reader, writer):
peer = writer.get_extra_info("peername")
writer.write(b":local.test NOTICE * :local Python IRCd ready\r\n")
await writer.drain()
while not reader.at_eof():
data = await reader.readline()
if not data:
break
if len(data) > 512:
writer.write(b"ERROR :line too long\r\n")
break
text = data.decode("utf-8", errors="replace").rstrip("\r\n")
if text.upper().startswith("PING "):
token = text.split(" ", 1)[1]
writer.write(f"PONG {token}\r\n".encode("utf-8"))
else:
writer.write(f":local.test NOTICE * :received from {peer}\r\n".encode("utf-8"))
await writer.drain()
writer.close()
await writer.wait_closed()
async def start_loopback_ircd():
server = await asyncio.start_server(handle_client, "127.0.0.1", 0)
host, port = server.sockets[0].getsockname()[:2]
print(f"loopback IRCd ready on {host}:{port}")
return server
if __name__ == "__main__" and False:
asyncio.run(start_loopback_ircd())
This final block is intentionally guarded. During validation it defines the server without opening a port. When you intentionally enable it in a lab, it still binds only to loopback. Do not expose a tutorial IRCd on the internet; put real services behind TLS, monitoring, rate limits, and a reviewed deployment plan.
The practical path is to keep the protocol code small and testable: parse lines, format replies, model registration, route channel messages, test byte framing locally, then connect those pieces to a loopback-only asyncio server. That gives you a clear Python IRCd foundation without pretending a tutorial script is a hardened chat network.
Separate Server Layers
Keep socket or asyncio transport handling, IRC line parsing, authentication, command dispatch, channel state, and outbound delivery as separate responsibilities. This makes protocol tests independent from the network loop.
Parse Safely
Apply message-length limits, handle CRLF framing, normalize only where the protocol permits it, and reject malformed commands without crashing the connection or leaking parser state.
Model State Explicitly
Track registered clients, nicknames, channels, membership modes, operators, and pending authentication in data structures with clear ownership. Avoid scattered global mutations that race during concurrent commands.
Authorize Every Action
JOIN, PRIVMSG, NICK, MODE, KICK, and administrative commands have different permission rules. Validate registration state, channel membership, nickname uniqueness, and operator privileges before mutation or broadcast.
Control Abuse And Failure
Rate-limit commands and messages, cap channel and connection resources, time out idle or incomplete frames, and remove all state when a client disconnects or a send fails.
Test A Local Deployment
Use local clients and fake transports to cover registration, joins, parts, private messages, nick changes, malformed lines, floods, half-closed sockets, reconnects, persistence choices, and graceful shutdown.
Use the IRC protocol specification for command and message behavior, and the official Python asyncio documentation for transport patterns. Related Python Pool references include testing and logging.
For related server design, compare protocol tests, operational logging, and state mappings before exposing an IRC service.
Frequently Asked Questions
What is an IRCd server?
An IRCd is an IRC server daemon that accepts client connections, parses IRC protocol messages, manages users and channels, and routes permitted messages.
Can Python be used to build an IRC server?
Yes, Python can handle the networking, protocol state, and command routing, but production use requires careful concurrency, security, protocol, and operational testing.
What should a Python IRCd validate?
Validate message framing, command syntax, nicknames, channel permissions, message lengths, authentication state, and rate limits before changing shared server state.
How do I test an IRC server safely?
Use local test clients and isolated fixtures to cover registration, joins, parts, private messages, malformed input, disconnects, floods, and graceful shutdown.
