Installing and running Sopel
NOTE: This guide is for Sopel 7.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 plugin.
If you want to use Python 3 on CentOS, you may want to see this guide on getting that set up easily.
Important: Sopel 8.0, the next major update, will support Python 3.6+ only.
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 extracted from the tarball) run
pip install -e .. During the installation process,
pip should install any
missing dependencies automatically. After it finishes, you can run
configure and start the bot.
Installing this way (an “editable” install) will let you tweak Sopel’s code to test out changes without having to reinstall the package every time you make an edit.
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.
- Upgrading from Willie 4.x to Willie 5.0
- Upgrading from Willie 5.x to Sopel 6.0
- Upgrading from Sopel 6.x to Sopel 7.0
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 plugins. This will automatically detect what plugins 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 configure. You can also get just the plugin options with
sopel configure --plugins. 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.
The easiest place to put new plugins is in
~/.sopel/plugins. Simply create
this directory if it does not exist, and drop
.py plugin files into it.
Sopel will auto-load them unless configured otherwise.
Plugin authors might also publish their works as packages; you can find them by searching PyPI, or by using your favorite search engine to search for e.g. “sopel weather plugin”.
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 plugins for Sopel? Continue to the tutorial!
Just want to play around with your new IRC bot? Read more usage articles!