Installing and running Sopel
NOTE: This guide is for Sopel 6.0+. If you are still using a version named “Willie”, we highly encourage you to upgrade, as such old versions are no longer supported.
Sopel requires Python 2.7.x or Python 3.3+ to run. Under Python 2.7, Sopel
backports.ssl_match_hostname to be installed. Use
python-backports.ssl_match_hostname to install it, or download and install it
manually from PyPI.
There is also a detailed system requirements page that is kept more-or-less updated (by a human) with what is required for each module.
If you want to use Python 3 on CentOS, you may want to see this guide on getting that set up easily.
Latest stable release
On most systems where you can run Python, the best way to install Sopel is to
sudo pip install sopel. (On Windows, leave out the
with pip will “just handle” dependencies for you, so you won’t need to do so
manually (except for installing
backports.ssl_match_hostname as described
above, if you’re on Python 2.7).
Nearly all Python versions Sopel supports should include pip out of the box. But
if your installation doesn’t have it, you’ll have to get it yourself. On Debian
and Ubuntu, you can do this by running
sudo apt-get install python-pip in a
terminal. For macOS and Windows, follow the
pip setup instructions
Arch users can install the
sopel package from the [community] repository,
though new versions might take slightly longer to become available.
Failing both of those options, you can grab the latest tarball from GitHub and follow the steps for installing from the latest source below.
First, either clone the repository with
git://github.com/sopel-irc/sopel.git or download a tarball from GitHub.
In the source directory (whether cloned or from the tarball) run
setup.py install. You can then run
sopel to configure and start the bot.
Alternately, you can just run the
sopel.py file in the source directory.
You will need to download all of Sopel’s dependencies and install them manually as well. These can be found on the Python Package Index. The only one that’s needed for the bot itself to work is backports.ssl_match_hostname. Other things are needed for modules to work properly. If you get errors about being unable to import modules when you start the bot, search for them on PyPI.
If you already have an older version of Sopel (or Willie) installed, and want to upgrade to the newest version, you should consult the migration guides.
You might need to read more than one if your existing Sopel instance is old enough. Each guide only covers migrating from the previous major version. So for example, if you still have Willie 4 running, and you want to get Sopel 6, you should read the Willie 5 migration guide (covers going from 4 to 5) and the Sopel 6 migration guide (covers going from 5 to 6).
Creating a service (optional)
Sopel’s source repository has example
systemd unit files in the
folder. Both single- (
and multi-instance (
sopel@.service) examples exist.
If you create a script or configuration file to run Sopel under another init system, feel free to submit it to the repo for other users’ convenience.
If you’re running Sopel on Windows, replace all following occurrences of
To run Sopel, just type the command
sopel in your terminal. The first time
you run Sopel, it will bring you through a quick setup wizard. Most of the
questions should be pretty straightforward. When you see something in square
brackets, that’s the default setting, and you can just hit enter to keep it.
When asked for the channels to connect to, enter them separated by commas
#spam,#eggs,#cheese) This wizard doesn’t cover every option, only the
ones which are needed to get the bot running. The core config settings are all
if you want to make other tweaks.
Finally, it will ask you about configuration settings for modules. This will automatically detect what modules you have available, and run their configuration utility if they have one.
Your configuration file will be stored in
~/.sopel. The file will be called
default.cfg by default. You can access the configuration wizard again by
sopel -w. You can also get just the module options with
sopel --configure-modules. You can specify another configuration file with
sopel -c filename. This works both for the configuration utility and for
running the bot. This way, you can keep multiple different config files for
different networks, for example. You can see a list of all these options by
sopel -h or
Once you’ve finished the configuration tool, Sopel will automatically start, connect to the network, and join the channels you specified.
Most IRC networks have a service that allows you to authenticate yourself as
the owner of a username. This is configurable in Sopel with these settings:
Want to learn how to write modules for Sopel? Continue to the tutorial!
Just want to play around with your new IRC bot? Read more usage articles!