Skip to main content

IRC (Internet Relay Chat) protocol client library for Python

Project description

The home of irclib is:

Documentation is available at:

Change history is available at:

You can download project releases from PyPI.

Tests are continually run using Travis-CI.


This library provides a low-level implementation of the IRC protocol for Python. It provides an event-driven IRC client framework. It has a fairly thorough support for the basic IRC protocol, CTCP, and DCC connections.

In order to understand how to make an IRC client, it’s best to read up first on the IRC specifications, available here:


IRC requires Python versions specified in the download pages and definitely supports Python 3.

You have several options to install the IRC project.

  • Use easy_install irc or pip install irc to grab the latest version from the cheeseshop (recommended).
  • Run python install (from the source distribution).

Client Features

The main features of the IRC client framework are:

  • Abstraction of the IRC protocol.
  • Handles multiple simultaneous IRC server connections.
  • Handles server PONGing transparently.
  • Messages to the IRC server are done by calling methods on an IRC connection object.
  • Messages from an IRC server triggers events, which can be caught by event handlers.
  • Reading from and writing to IRC server sockets is normally done by an internal select() loop, but the select() may be done by an external main loop.
  • Functions can be registered to execute at specified times by the event-loop.
  • Decodes CTCP tagging correctly (hopefully); I haven’t seen any other IRC client implementation that handles the CTCP specification subtilties.
  • A kind of simple, single-server, object-oriented IRC client class that dispatches events to instance methods is included.
  • DCC connection support.

Current limitations:

  • The IRC protocol shines through the abstraction a bit too much.
  • Data is not written asynchronously to the server (and DCC peers), i.e. the write() may block if the TCP buffers are stuffed.
  • Like most projects, documentation is lacking …

Unfortunately, this library isn’t as well-documented as I would like it to be. I think the best way to get started is to read and understand the example program irccat, which is included in the distribution.

The following files might be of interest:

  • irc/

    The library itself. Read the code along with comments and docstrings to get a grip of what it does. Use it at your own risk and read the source, Luke!

  • irc/

    An IRC bot implementation.

  • irc/

    A basic IRC server implementation. Suitable for testing, but not production quality.


Example scripts in the scripts directory:

  • irccat

    A simple example of how to use the IRC client. irccat reads text from stdin and writes it to a specified user or channel on an IRC server.

  • irccat2

    The same as above, but using the SimpleIRCClient class.

  • servermap

    Another simple example. servermap connects to an IRC server, finds out what other IRC servers there are in the net and prints a tree-like map of their interconnections.

  • testbot

    An example bot that uses the SingleServerIRCBot class from The bot enters a channel and listens for commands in private messages or channel traffic. It also accepts DCC invitations and echos back sent DCC chat messages.

  • dccreceive

    Receives a file over DCC.

  • dccsend

    Sends a file over DCC.

NOTE: If you’re running one of the examples on a unix command line, you need to escape the # symbol in the channel. For example, use \\#test or "#test" instead of #test.

Decoding Input

By default, the IRC library attempts to decode all incoming streams as UTF-8, even though the IRC spec stipulates that no specific encoding can be expected. Since assuming UTF-8 is not reasonable in the general case, the IRC library provides options to customize decoding of input by customizing the ServerConnection class. The buffer_class attribute on the ServerConnection determines which class is used for buffering lines from the input stream. By default it is buffer.DecodingLineBuffer, but may be re-assigned with another class, following the interface of buffer.LineBuffer. The buffer_class attribute may be assigned for all instances of ServerConnection by overriding the class attribute.

For example:

irc.client.ServerConnection.buffer_class = irc.buffer.LenientDecodingLineBuffer

The LenientDecodingLineBuffer attempts UTF-8 but falls back to latin-1, which will avoid UnicodeDecodeError in all cases (but may produce unexpected behavior if an IRC user is using another encoding).

The buffer may be overridden on a per-instance basis (as long as it’s overridden before the connection is established):

server = irc.client.IRC().server()
server.buffer_class = irc.buffer.LenientDecodingLineBuffer

Alternatively, some clients may still want to decode the input using a different encoding. To decode all input as latin-1 (which decodes any input), use the following:

irc.client.ServerConnection.buffer_class.encoding = 'latin-1'

Or decode to UTF-8, but use a replacement character for unrecognized byte sequences:

irc.client.ServerConnection.buffer_class.errors = 'replace'

Or, to simply ignore all input that cannot be decoded:

class IgnoreErrorsBuffer(irc.buffer.DecodingLineBuffer):
    def handle_exception(self):
irc.client.ServerConnection.buffer_class = IgnoreErrorsBuffer

On Python 2, it was possible to use the buffer.LineBuffer itself, which will pass the raw bytes. On Python 3, the library requires text for message processing, so a decoding buffer must be used. Therefore, use of the LineBuffer is considered deprecated and not supported on Python 3. Clients should use one of the above techniques for decoding input to text.

Notes and Contact Info


Maintainer: Jason R. Coombs <>

Original Author: Joel Rosdahl <>

Copyright © 1999-2002 Joel Rosdahl Copyright © 2011-2015 Jason R. Coombs Copyright © 2009 Ferry Boender

Project details

Release history Release notifications

Download files

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

Files for irc, version 13.3.1
Filename, size File type Python version Upload date Hashes
Filename, size irc-13.3.1-py2.py3-none-any.whl (75.3 kB) File type Wheel Python version 3.5 Upload date Hashes View hashes
Filename, size irc-13.3.1.tar.gz (81.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page