irc3. pluggable irc client library based on python’s asyncio

A pluggable irc client library based on python’s asyncio.

Ceative Commons – Attribution (CC BY 3.0) - Hydra designed by Huu Nguyen from the Noun Project -

Requires python 3.3+

Python 2 is no longer supported, but if you don’t have a choice you can use an older version:

$ pip install "irc3<0.9"



Irc: irc:// (www)

Twitter: @python_irc3


Using pip:

$ pip install irc3

Quick start

irc3 provides a basic template to help you to quickly test a bot. Here is how to create a bot named mybot.

Create a new directory and cd to it:

$ mkdir mybot
$ cd mybot

Then use the template:

$ python -m irc3.template mybot

This will create an almost ready to use config.ini file and a simple plugin named that says «Hi» when the bot or someone else joins a channel and includes an echo command.

Here is what the config file will looks like:

nick = mybot
username = mybot

host = localhost
port = 6667

# uncomment this if you want ssl support
# ssl = true
# uncomment this if you don't want to check the certificate
# ssl_verify = CERT_NONE

# uncomment this if you want to use sasl authentication
# sasl_username = mybot
# sasl_password = yourpassword

includes =
#    irc3.plugins.uptime
#    irc3.plugins.ctcp

# the bot will join #mybot_channel
# ${hash} is replaced by the # char
autojoins =

# Autojoin delay, disabled by default
# float or int value
# autojoin_delay = 3.1

# The maximum amount of lines irc3 sends at once.
# Default to 4, set to 0 to disable
# flood_burst = 10

# The number of lines per $flood_rate_delay seconds irc3 sends after reaching
# the $flood_burst limit.
# Default to 1
# flood_rate = 2

# The bot will send $flood_rate messages per $flood_rate_delay seconds
# Default to 1
# flood_rate_delay = 5

# command plugin configuration

# set command char
cmd = !

# set guard policy
guard = irc3.plugins.command.mask_based_policy

# this section is used by the guard to secure the bot's command
# change your nickname and uncomment the line below
# mynick!*@* = all_permissions
* = view

And here is the plugin:

# -*- coding: utf-8 -*-
from irc3.plugins.command import command
import irc3

class Plugin(object):

    def __init__(self, bot): = bot

    def say_hi(self, mask, channel, **kw):
        """Say hi when someone join a channel"""
        if mask.nick !=
  , 'Hi %s!' % mask.nick)
  , 'Hi!')

    def echo(self, mask, target, args):

            %%echo <message>...
        yield ' '.join(args['<message>'])

Have a look at those file and edit the config file for your needs. You may have to edit:

  • the autojoin channel
  • your irc mask in the irc3.plugins.command.mask section

Once you’re done with editing, run:

$ irc3 config.ini

Check the help of the irc3 command.

$ irc3 -h

If you’re enjoying it, you can check for more detailed docs below. And some more examples here:

Indices and tables