Create a virtual environment

Please use a python virtual environment. It keeps everybody on the same page, helps reproducing bugs and resolving problems.

We highly suggest to use virtualenvwrapper, please refer to the official virtualenvwarpper installation page and come back here when ready to proceed.

# create virtualenv
mkvirtualenv radius


If you encounter an error like Python could not import the module virtualenvwrapper, add VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3 and run source again :)

Install stable version from pypi

Install from pypi:

pip install django-freeradius

Install development version

Install tarball:

pip install

Alternatively you can install via pip using git:

pip install -e git+git://

If you want to contribute, install your cloned fork:

git clone<your_fork>/django-freeradius.git
cd django-freeradius
python develop

Setup (integrate in an existing django project)

In the django file of your project, do the following:

  • add django_freeradius and django_filters to INSTALLED_APPS
  • set DJANGO_FREERADIUS_API_TOKEN (see API Token for more information):
    # other apps

DJANGO_FREERADIUS_API_TOKEN = '<a-long-secret-value-of-your-choice>'

Add the URLs to your main

urlpatterns = [
    # ... other urls in your project ...

    # django-freeradius urls
    # keep the namespace argument unchanged
    url(r'^', include('django_freeradius.urls', namespace='freeradius')),

Then run:

./ migrate

Migrating an existing freeradius database

If you already have a freeradius 3 database with the default schema, you should be able to use it with django-freeradius (and openwisp-radius) easily:

  1. first of all, back up your existing database;
  2. configure django to connect to your existing database;
  3. fake the first migration (which only replicates the default freeradius schema) and then launch the rest of migrations normally, see the examples below to see how to do this.


./ migrate --fake django_freeradius 0001_initial_freeradius
./ migrate


In case you are using openwisp-radius:

./ migrate --fake openwisp_radius 0001_initial_freeradius
./ migrate

Installing for development

Install sqlite:

sudo apt-get install sqlite3 libsqlite3-dev

Install mysqlclient:

sudo apt-get install libmysqlclient-dev

Install your forked repo:

git clone git://<your_username>/django-freeradius
cd django-freeradius/
python develop

Install test requirements:

pip install -r requirements-test.txt

Create database:

cd tests/
./ migrate
./ createsuperuser

Launch development server:

./ runserver

You can access the admin interface at

Run tests with:


Automating management commands

Some management commands are necessary to enable certain features and also facilitate database cleanup. In a production environment, it is highly recommended to automate the usage of these commands by using cron jobs.

Edit the crontab with:

crontab -e

Add and modify the following lines accordingly:

# This command deletes RADIUS accounting sessions older than 365 days
30 04 * * * <virtualenv_path>/bin/python <full/path/to>/ delete_old_radacct 365

# This command deletes RADIUS post-auth logs older than 365 days
30 04 * * * <virtualenv_path>/bin/python <full/path/to>/ delete_old_postauth 365

# This command closes stale RADIUS sessions that have remained open for 15 days
30 04 * * * <virtualenv_path>/bin/python <full/path/to>/ cleanup_stale_radacct 15

# This command deactivates expired user accounts which were created temporarily
# (eg: for en event) and have an expiration date set.
30 04 * * * <virtualenv_path>/bin/python <full/path/to>/ deactivate_expired_users

# This command deletes users that have expired (and should have
# been deactivated by deactivate_expired_users) for more than
# 18 months (which is the default duration)
30 04 * * * <virtualenv_path>/bin/python <full/path/to>/ delete_old_users

Be sure to replace <virtualenv_path> with the full path to the Python virtual environment.

Also, change <full/path/to> to the directory where is.

To get the full path to when django-freeradius is installed for development, navigate to the base directory of the cloned fork. Then, run:

cd tests/

More information can be found at the management commands page.