OrangeAssassin is an open-source drop-in replacement for SpamAssassin.


OrangeAssassin is compatible with the following Python versions:

  • Python 2.7
  • Python 3.2 and later
  • PyPy
  • PyPy3

Getting the source

To clone the repository using git simply run:

git clone

Please feel free to fork us and submit your pull requests.

Running tests

To run the project’s tests you will need to first:

  1. Create a python virtualenv and activate it (Recommended only)
  2. Clone the repository from GitHub.
  3. Install sqlalchemy or pymysql package.
  4. Install the base dependencies from requirements/base.txt with pip
  5. Install the the dependencies for the python version you are using from the requirements folder
  6. Install the dependencies for running tests from requirements/tests.txt
  7. Download the GeoIP databases (for IPv4 and IPv6)
  8. Run the script


Some requirements (e.g. Pillow) require some additional build dependencies when installing them.

The OrangeAssassin tests are split into unittest and functional tests.

Unitests perform checks against the current source code and not the installed version of OrangeAssassin. To run all the unittests suite:

py.test tests/unit/

Functional tests perform checks against the installed version of OrangeAssassin and not the current source code. These are more extensive and generally take longer to run. They also might need special setup. To run the full suite of functional tests:

env USE_PICKLES=0 py.test tests/functional/ (or py.test tests/functional/)

If you want to compile rules and avoid re-parsing:

env USE_PICKLES=1 py.test tests/functional/

Or you can run all the tests with just:


An example for Python3 would be:

sudo apt-get install python3-dev libjpeg-dev build-essential zlib1g-dev
virtualenv -p /usr/bin/python3 ~/oa-env
source ~/oa-env/bin/activate
git clone
cd OrangeAssassin
pip install sqlalchemy || pip install pymysql
pip install -r requirements/base.txt
pip install -r requirements/python3.txt
pip install -r requirements/tests.txt
gunzip GeoIP.dat.gz
gunzip GeoIPv6.dat.gz
python install
env USE_PICKLES=0 py.test
env USE_PICKLES=0 py.test


See also the .travis.yml file where all these instructions are set for the automatic builds.

Building documentation

In order to build the documentation based on the docs files from the repository:

  1. Run the same steps for running the tests (including installing all requirements, installing OrangeAssassin, etc.).
  2. Install the documentation libraries from requirements/docs.txt
  3. Change directory to docs
  4. Run make html
  5. The HTML version of the documentation will be generated in the docs/_build/ directory.

See also the helper script docs/ that generates a documentation page for the specified plugin. After adding a new plugin:

  • Use the script to generate a new page for it
  • Add a reference to the list from docs/plugins.rst
  • Add autodoc to docs/pad.plugins.rst


This program is free software; you can redistribute it and/or modify it under the terms of the Apache Software Foundation License version 2 only of the License.