.. _install:


Installation guide
==================

The |release| version of ``akismet`` is officially tested and supported on the following
versions of Python:

* Python 3.10

* Python 3.11

* Python 3.12

* Python 3.13

* Python 3.14


Installing ``akismet``
----------------------

To install the latest stable released version of ``akismet``, run the following command
from a command prompt/terminal:

.. tab:: macOS/Linux/other Unix

   .. code-block:: shell

      python -m pip install --upgrade akismet

.. tab:: Windows

   .. code-block:: shell

      py -m pip install --upgrade akismet

This will use ``pip``, the standard Python package-installation tool. If you are using a
supported version of Python, your installation of Python should have come with ``pip``
bundled. If ``pip`` does not appear to be present, you can try running the following
from a command prompt/terminal:

.. tab:: macOS/Linux/other Unix

   .. code-block:: shell

      python -m ensurepip --upgrade

.. tab:: Windows

   .. code-block:: shell

      py -m ensurepip --upgrade

Instructions are also available for `how to obtain and manually install or upgrade pip
<https://pip.pypa.io/en/latest/installation/>`_.


Configuration
-------------

To use this library, you will need to obtain an Akismet API key and register a site for
use with the Akismet web service; you can do this at <https://akismet.com>. Once you
have a key and corresponding registered site URL to use with it, place them in the
environment variables ``PYTHON_AKISMET_API_KEY`` and ``PYTHON_AKISMET_BLOG_URL``, and
they will be automatically detected and used.

You can also optionally set the environment variable ``PYTHON_AKISMET_TIMEOUT`` to a
:class:`float` or :class:`int` containing a connection-timeout threshold to use for
making requests to the Akismet web service; if not set, this will default to ``1.0``
(one second).


.. _source-install:

Installing for local development
--------------------------------

If you want to work on ``akismet``, you can obtain a source checkout.

The development repository for ``akismet`` is at
<https://github.com/ubernostrum/akismet>. If you have `git <http://git-scm.com/>`_
installed, you can obtain a copy of the repository by typing::

    git clone https://github.com/ubernostrum/akismet.git

Then follow the instructions in the file ``CONTRIBUTING.rst`` in the root directory of
the source checkout.