# Sopel: a Python IRC bot framework that plugins extend

> Sopel is a Python IRC bot framework where behaviour lives in plugins rather than in a configuration file. It ships a database layer built on SQLAlchemy, an installable plugin ecosystem on PyPI, and a documented API, and it still expects a real IRC server on the other end.

**sopel-irc/sopel** — :robot::speech_balloon: An easy-to-use and highly extensible IRC Bot framework. Formerly Willie.

- Repository: https://github.com/sopel-irc/sopel
- Website: https://sopel.chat
- Stars: 984 · Forks: 418
- Language: Python
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/sopel-irc-sopel

## Behaviour lives in plugins, not in a config file

Most bot frameworks split into two camps: a configuration file that declares what the bot does, or a code framework that lets you write anything. Sopel takes the second route, and the plugin model is its defining idea.

The documentation describes Sopel as a simple, lightweight, open source IRC utility bot written in Python, designed to be easy to use, run and extend. Extend is the operative word. A new capability is a Python module with a decorated function, not a stanza in a settings file. The easiest place to put new plugins is ~/.sopel/plugins, and the project points at a tutorial for writing plugins on its own website, plus API documentation at sopel.chat/docs.

Distribution is the part that has changed over time. Newer plugins are installable as packages, and the documentation suggests searching PyPI for sopel to find them. Older, unmaintained plugins live in a separate sopel-extras repository. So there are three routes for a plugin: pip install a package, drop a file into the plugins directory, or write your own.

The target audience is spelled out in the package classifiers: Developers and System Administrators. That is the pairing to keep in mind. Sopel is not a chat product, it is a tool that a system administrator runs on a box and that a developer extends.

## Installing from pip, from a tarball or from source

The installation section gives three routes, and the order matters because the first one is the one most people should take.

On most systems where you can run Python, the documented best way to install Sopel is to install pip and then:

```bash
pip install sopel
```

Arch users can install the sopel package from the community repository, with the caveat that new versions might take slightly longer to become available there. If neither route works, the fallback is to grab the latest tarball from the GitHub releases page and follow the source instructions.

The source path starts with a clone or a source archive:

```bash
git clone https://github.com/sopel-irc/sopel.git
```

Then, in the source directory, whether cloned or unpacked from the tarball:

```bash
pip install -e .
```

After that you can run sopel to configure and start the bot. That first run is the configuration step, and it is where the connection details and the plugin set are settled.

One constraint is stated plainly: Sopel requires Python 3.8 or newer to run. The package metadata lists classifiers for Python 3.8 through 3.15 and declares requires-python as >=3.8, so the floor is consistent across the documentation and the manifest.

## Storage runs through SQLAlchemy, SQLite by default

A bot that only answers commands is not much use. Sopel plugins that need to remember things get a database layer, and the documentation states that Sopel uses SQLAlchemy to support a list of backends: SQLite, MySQL, PostgreSQL, MSSQL, Oracle, Firebird and Sybase.

By default Sopel uses a SQLite database in the current configuration directory, which means a fresh install needs no database server at all. Moving to a different backend is a matter of configuration options, and the names are spelled out: db_type, db_filename for SQLite only, db_driver, db_user, db_pass, db_host, db_port and db_name.

The catch is stated in the same section. You have to install the packages your chosen database needs yourself, either system packages or pip, and there is an explicit warning that plugins not updated since Sopel 7.0 was released might have problems with database types other than SQLite, though many will work just fine. That is a compatibility boundary worth respecting: on a non-SQLite backend, a stale plugin is a likely source of breakage.

The dependency pin is narrow. The manifest requires sqlalchemy>=1.4,<1.5, so the project is on the SQLAlchemy 1.4 series rather than 2.x. Other runtime dependencies are pytz, requests with a ceiling below 3.0.0, importlib_metadata, packaging, sopel-help and typing_extensions, the last one noted in the file as needed for the override decorator added in Python 3.12.

## The Makefile shows how the project itself is worked on

The repository's Makefile is a compact description of the development workflow, and it is useful to a contributor.

Quality assurance is a single target that chains the others:

```bash
qa: lint test coverages
```

Lint splits into style and type checking, with flake8 for the first and mypy pointed at the sopel package for the second. Tests run under coverage with pytest, and there is a coverage report and HTML output target alongside them.

The VCR targets are the interesting part. test_norecord runs pytest with vcr-record=none, and the comment says it errors if a VCR recording for a web request is missing, which is useful on CI. test_novcr disables VCR entirely, described as useful to check whether recordings are outdated. vcr_rerecord clears the cassettes in test/vcr and re-records them. In other words, the HTTP calls that plugins make during tests are captured as cassettes, and the project treats a stale cassette as something to notice rather than something to ignore.

Documentation has its own targets, with build_docs delegating into the docs directory, and there are install-hooks targets that run the git hook installer from contrib/githooks. The layout at the root shows a sopel package directory, a test directory, a docs directory, a contrib directory, and the standard packaging files including pyproject.toml and a COPYING file that holds the licence.

## Licence and release cadence

The licence is worth reading carefully because it is not one of the usual permissive licences. The package metadata declares license as EFL-2.0, the Eiffel Forum License, and the classifiers list the Eiffel Forum License both under its own name and under OSI Approved. The repository metadata itself reports a custom licence that GitHub cannot classify, and points to the licence file for the exact terms. Read COPYING in the repository for the authoritative text rather than relying on a summary.

The Eiffel Forum Licence is a source-available licence with a distribution requirement rather than a copyleft one, and it was chosen by the project deliberately rather than by accident. If your organisation has a standard approval checklist for licences, EFL-2.0 will need a legal review, and you should not read the presence of a permissive-looking ecosystem around it as a substitute for that review.

On versions, the manifest declares 8.1.0.dev0, which marks the development line ahead of the last stable release. The published releases are v8.0.4 on 2025-08-27, v8.0.3 on 2025-07-11 and v8.0.2 on 2025-02-05. The last push to the repository was on 2026-10-17, so work is continuing between releases rather than the project sitting idle.

The project also runs a presence on Libera Chat under the #sopel channel, which is where the maintainers and users meet for questions that the documentation does not answer.

## Where Sopel is the wrong choice

The clearest limitation is the protocol. Sopel is an IRC bot framework, and IRC means a server, a channel, and a bot account that has been given appropriate permissions. If the goal is a bot on a platform where the community has already moved, the transport will not carry over, and the value of the plugin ecosystem drops with it because most plugins assume an IRC-shaped command and a channel.

The second limitation is the plugin ecosystem's shape. The easiest installation path is a file copied into ~/.sopel/plugins, which means a shared machine can end up with plugins from several sources and different versions of the same plugin, and the documentation itself segregates unmaintained plugins into a separate sopel-extras repository. Package installation is available for newer plugins, but there is no dependency resolution described for plugins, no version constraints and no compatibility matrix between a plugin and a Sopel release.

The third is the database pin. The sqlalchemy>=1.4,<1.5 constraint means an application that already depends on SQLAlchemy 2.x cannot share an environment with this Sopel, and the warning about plugins that predate Sopel 7.0 on non-SQLite backends means a shared database across bots carries a compatibility question per plugin.

One more practical point: there is no schedule of release notes in the repository listing, only tagged releases and a NEWS file, and the version currently in development is 8.1.0.dev0, so anyone pinning to a release should read the changelog between 8.0.4 and 8.1.0 before upgrading.

## Conclusion

Sopel suits an operator who wants a bot on an existing IRC network with commands, schedules and stored state written in Python, especially where a plugin package on PyPI already covers the job. It does not suit anyone expecting a modern chat platform integration, because the framework speaks IRC and its ecosystem still leans on shared plugin directories for distribution. Before adopting it, check the SQLAlchemy pin in pyproject.toml, which sits on the 1.4 series, and confirm your Python is 3.8 or newer, since that is the declared floor for both the runtime and the classifier list.

## FAQ

### How do I install Sopel?

On most systems the documented method is pip install sopel. Arch users can install the sopel package from the community repository, and otherwise you can clone the repository and run pip install -e . in the source directory, then run sopel to configure and start the bot.

### Which Python versions does Sopel support?

Sopel requires Python 3.8 or newer. The package metadata declares requires-python as >=3.8 and lists classifiers for Python 3.8 through 3.15.

### Where do I put a new Sopel plugin?

The easiest place is the ~/.sopel/plugins directory. Newer plugins can also be installed as packages from PyPI, and the project keeps older unmaintained ones in a separate sopel-extras repository.

### What database does Sopel use and can I change it?

By default Sopel uses a SQLite database in the current configuration directory. It supports SQLite, MySQL, PostgreSQL, MSSQL, Oracle, Firebird and Sybase through SQLAlchemy, configured with options such as db_type, db_driver, db_user, db_pass, db_host, db_port and db_name.

### What licence is Sopel released under?

The package metadata declares EFL-2.0, the Eiffel Forum License, which the classifiers list as OSI Approved. The repository holds the licence text in the COPYING file, and the repository metadata describes it as a custom licence.

## Sources

- [Issues](https://github.com/sopel-irc/sopel/issues)
- [Project website](https://sopel.chat)
- [README](https://github.com/sopel-irc/sopel/blob/master/README.md)
- [Releases](https://github.com/sopel-irc/sopel/releases)
- [sopel-irc/sopel on GitHub](https://github.com/sopel-irc/sopel)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sopel-irc-sopel