You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
dgw a5a6e2dcf3
Merge pull request #1901 from sopel-irc/document-env-vars
3 days ago
.github Add Python version to bug report issue template 4 months ago
contrib contrib: remove unused import in 7 months ago
docs doc: a bit more info about plugin names (conventions & how to specify) 4 days ago
sopel Merge pull request #1901 from sopel-irc/document-env-vars 3 days ago
test test: add coverage for `SOPEL_CONFIG_DIR` environment variable 1 week ago
.codeclimate.yml Tweak some thresholds in codeclimate config 1 year ago
.coveragerc test: update web -> tools.web; ignore deprecated package 11 months ago
.gitignore test: py.test Sopel plugin with test factories 7 months ago
.travis.yml travis: modernize base build images when possible 2 months ago CONTRIBUTING: Additional tweaks 1 month ago
COPYING Added EFL license file, to actually comply with it 7 years ago
CREDITS CREDITS: RustyBower name update, per IRC request [Skip CI] 6 months ago install: use setup.cfg instead of 1 year ago
Makefile module, tests: set up `` for plugin example tests 1 month ago
NEWS Release 7.0.4 1 month ago NEWS, NEWS.spec: 7.0+ will use a "Plugin changes" heading 5 months ago
README.rst README: Clean up some stuff for PyPI 5 months ago checkstyle: Fix py3-unsafe unicode() detection 1 year ago Update to be useful again 2 years ago test: provide "path" instead of "dir" fixture for old pytest-vcr 1 month ago
dev-requirements.txt module, tests: set up `` for plugin example tests 1 month ago
pytest.ini Update to testing process 2 years ago Cleaning for flake8-import-order 1 month ago
requirements.txt requirements: cap urllib3 version on old Python releases 2 months ago
setup.cfg Cleaning for flake8-import-order 1 month ago Cleaning for flake8-import-order 1 month ago Cleaning for flake8-import-order 1 month ago



|version| |build| |issues| |alerts| |coverage-status| |license|


Sopel is a simple, lightweight, open source, easy-to-use IRC Utility bot,
written in Python. It's designed to be easy to use, run and extend.


Latest stable release
On most systems where you can run Python, the best way to install Sopel is to
install `pip <>`_ and then ``pip install sopel``.

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.

Latest source
First, either clone the repository with ``git clone
git://`` or download a tarball `from GitHub

Note: Sopel requires Python 2.7.x or Python 3.3+ to run. On Python 2.7,
Sopel requires ``backports.ssl_match_hostname`` to be installed. Use
``pip install backports.ssl_match_hostname`` or
``yum install python-backports.ssl_match_hostname`` to install it, or download
and install it manually `from PyPI <>`_.

Note: Python 2.x is near end of life. Sopel will drop support in version 8.0.

In the source directory (whether cloned or from the tarball) run ``pip install
-e .``. You can then run ``sopel`` to configure and start the bot.

Database support
Sopel leverages SQLAlchemy to support the following database types: SQLite,
MySQL, PostgreSQL, MSSQL, Oracle, Firebird, and Sybase. By default Sopel will
use a SQLite database in the current configuration directory, but alternative
databases can be configured with the following config options: ``db_type``,
``db_filename`` (SQLite only), ``db_driver``, ``db_user``, ``db_pass``,
``db_host``, ``db_port``, and ``db_name``. You will need to manually install
any packages (system or ``pip``) needed to make your chosen database work.

**Note:** Plugins not updated since Sopel 7.0 was released *might* have
problems with database types other than SQLite (but many will work just fine).

Adding plugins
The easiest place to put new plugins is in ``~/.sopel/plugins``. Some newer
plugins are installable as packages; `search PyPI
<>`_ for these. Many more plugins
written by other users can be found using your favorite search engine.

Some older, unmaintained plugins are available in the
`sopel-extras <>`_ repository, but of
course you can also write your own. A `tutorial <>`_
for creating new plugins is available on Sopel's website.
API documentation can be found online at, or
you can create a local version by running ``make docs``.

Further documentation

The `official website <>`_ includes such valuable information
as a full listing of built-in `commands <>`_,
`tutorials <>`_, `API documentation <>`_,
and other `usage information <>`_.


Join us in `#sopel <irc://>`_ on Freenode.

Financial support

We're thrilled that you want to support the project!

We have applied for access to organization-level sponsorship from GitHub. In
the interim, if you wish to contribute sooner, you are welcome to do so
through `Open Collective <>`_ or sponsor
Sopel's maintainer, `dgw <>`_, individually.

Any donations received will be used to cover infrastructure costs, such as our
domain name and hosting services. Our main project site is easily hosted by
`Netlify <>`_, but we are considering building a few
new features that would require more than static hosting. All project-related
`expenses <>`_ are tracked on our
Open Collective profile, for transparency.

.. |version| image::
.. |build| image::
.. |issues| image::
.. |alerts| image::
.. |coverage-status| image::
.. |license| image::