Skip to main content

Store your GPX tracks of your running (or other sports activity) in django.

Project description

Logo Store your GPX tracks of your running (or other sports activity) in django.

Build Status on github
Coverage Status on
Coverage Status on

(The name Django-ForRunners has the origin from the great Android tracking app ForRunners by Benoît Hervier: )


  • GPX track management:

    • Upload GPX tracks

    • Import GPX tracks from commandline

    • Track analysis:

      • basics: Track length / Duration / Pace / Hart rate Up-/Downhill
      • Display route on OpenStreetMap map
      • Graphs with elevation / heart rate / cadence (if available in GPX data)
    • Data that is automatically extracted from the web:

      • Start/finish Address from OpenStreetMap
      • Start/finish weather information from
    • Store additional data:

      • Ideal track distance (for easier grouping/filtering tracks)
  • sports competitions Management:

    • Create a List of Sport Events

      • Add participation to a event

      • link GPX track with a event participation

      • Store you event participation:

        • official track length
        • measured finisher time
        • Number of participants who have finished in your discipline
      • Add links to webpages relatet to this event

      • Record costs (entry fee, T-shirt etc.)

  • common

    • Multiple user support (However: no rights management and currently only suitable for a handful of users)

Project structure

There are two main directories:

directory description
`/src/`_ The main Django-ForRunners source code
`/deployment/`_ deploy Django-ForRunners for production use case


There exists two kind of installation/usage:

This README contains only the information about local development installation.

Read /deployment/README for instruction to install Django-ForRunners on a root server.


~$ git clone
~$ cd django-for-runners/
~/django-for-runners$ make
DjangoForRunners - *dev* Makefile

install-poetry         install or update poetry
install                install DjangoForRunners via poetry
manage-update          Collectstatic + makemigration + migrate
update                 update the sources and installation
lint                   Run code formatters and linter
fix-code-style         Fix code formatting
tox-listenvs           List all tox test environments
tox                    Run pytest via tox with all environments
tox-py36               Run pytest via tox with *python v3.6*
tox-py37               Run pytest via tox with *python v3.7*
tox-py38               Run pytest via tox with *python v3.8*
pytest                 Run pytest
update-rst-readme      update README.rst from README.creole
publish                Release new version to PyPi
run-dev-server         Run the django dev server in endless loop.
createsuperuser        Create super user
messages               Make and compile locales message files
dbbackup               Backup database
dbrestore              Restore a database backup
run-docker-dev-server  Start docker containers with current dev source code

local development installation

# install or update Poetry:
~/django-for-runners$ make install-poetry

# install  Django-ForRunners via poetry:
~/django-for-runners$ make install

# Collectstatic + makemigration + migrate:
~/django-for-runners$ make manage-update

# Create a django super user:
~/django-for-runners$ ./ createsuperuser

# start local dev. web server:
~/django-for-runners$ make run-dev-server

The web page is available in Port 8000, e.g.:

local docker dev run

You can run the deployment docker containers with current source code with:

~/django-for-runners$ make run-docker-dev-server

Just hit Cntl-C to stop the containers

The web page is available on Port 80, e.g.: http://localhost/

import GPX files


~/django-for-runners$ poetry run manage import_gpx --username <django_username> ~/backups/gpx_files

Note: It is no problem to start import_gpx with the same GPX files: Duplicate entries are avoided. The start/finish (time/latitude/longitude) are compared.


Create a backup into .../backups/<timestamp>/ e.g.:

~/django-for-runners$ poetry run for_runners backup

The backup does:

  • backup the database
  • export all GPX tracks
  • generate .csv files:
  • a complete file with all running tracks
  • one file for every user

regenerate all SVG files

~/django-for-runners$ poetry run for_runners recreate-svg

for-runers v0.6.0 2018-07-31 GPX Track.png

for-runers v0.6.0 2018-07-31 GPX Track.png

for-runners v0.4.0 2018-6-26 GPX info.png

for-runners v0.4.0 2018-6-26 GPX info.png

for-runners v0.6.0 2018-07-19 Event Costs.png

for-runners v0.6.0 2018-07-19 Event Costs.png

run tests

~/Django-ForRunners$ make test


~/Django-ForRunners$ make tox


To run all tests, you need:

  • Chromium Browser WebDriver e.g.: apt install chromium-chromedriver
  • Firefox Browser WebDriver aka geckodriver

install geckodriver e.g.:

~$ cd /tmp
/tmp$ wget -O geckodriver.tar.gz
/tmp$ sudo sh -c 'tar -x geckodriver -zf geckodriver.tar.gz -O > /usr/bin/geckodriver'
/tmp$ sudo chmod +x /usr/bin/geckodriver
/tmp$ rm geckodriver.tar.gz
/tmp$ geckodriver --version
geckodriver 0.20.1

some notes

GPX storage

Currently we store the unchanged GPX data in a TextField.

static files

We collect some JavaScript files, for easier startup. These files are:

Project Homepage License storage directory Leaflet licensed under BSD for_runners/static/leaflet/ dygraphs licensed under MIT for_runners/static/dygraphs/ Chart.js licensed under MIT for_runners/static/chartjs/

Precision of coordinates

GPX files from Garmin (can) contain:

  • latitude with 29 decimal places
  • longitude with 28 decimal places
  • elevation with 19 decimal places

The route on OpenStreetMap does not look more detailed, with more than 5 decimal places.

See also:

Django compatibility

django-for-runners django version python
>=v0.11.0 2.2.x LTS 3.6, 3.7, 3.8
>=v0.7.1 2.1 3.5, 3.6, 3.7
v0.5.x 2.0 3.5, 3.6, 3.7

(See also combinations in .travis.yml and tox.ini)

Backwards-incompatible changes

Older changes, see:


Move main project sources into “/src/” Add deployment setup into “/development/”


  • compare v0.12.0…master dev

    • tbc
  • 17.01.2021 - v0.12.0:

  • 04.07.2020 - v0.11.0:

    • refactor gpx import code
    • update tests
    • Use poetry and add Makefile
    • update code style
  • 09.08.2019 - v0.10.1:

    • Enhance “Event Participation” admin view: Add start date and costs in table
  • 26.06.2019 - v0.10.0:

    • NEW: GPX Admin action to print a small overview from one or a few tracks
    • Accept optional server bind address, e.g.: for_runners run-server
  • 02.04.2019 - v0.9.0:

    • NEW: Update complete environment installation with: for_runners update

    • Move the SQlite database to virtualenv root dir, e.g.: ~/Django-ForRunners/Django-ForRunners-database.sqlite3

    • NEW: save every gpx track to disk

    • NEW: Backup/export via cli: $ for_runners backup

    • NEW: export GPX Data via django-import-export

    • Create xdg-open desktop starter under linux here: ~/Django-ForRunners/Django-ForRunners

    • refactor the startup process:

      • auto loop the server process
      • open web browser on first start
      • enable autotask
    • rename for_runners_test_project to for_runners_project

  • 03.09.2018 - v0.8.1:

    • Fix “try-out” section in README, again ;(
  • 03.09.2018 - v0.8.0:

    • NEW: shell script for easier boot/install, see above
  • 02.09.2018 - v0.7.1:

    • Update to Django 2.1
    • Bugfix Tests
  • 02.09.2018 - v0.7.0:

    • Use dygraphs in GPX Track change admin view

    • Sync mouse over from Elevation/Headrate/Cadence dygraphs to leaflet open streep map

    • Fix “try-out” section in README (Thanks adsworth for reporting)

    • Add links from gpx tracks to other admin change view

    • Bugfixes

    • internals:

      • refactor stuff around track duration/length
      • move manipluation of list_display and list_filter contributed by adsworth
  • 19.07.2018 - v0.6.0:

    • NEW: event participation
    • NEW: costs of event participation (e.g.: entry fee for the competition, cost of a T-Shirt etc.)
    • NEW: Display statistics of events/costs per user and total
  • 04.07.2018 - v0.5.0:

    • remove Django-CMS
    • update to Django v2.0
    • NOTE: The migrations are simply replaced! So you must delete your database, e.g.: src/django-for-runners$ rm test_project_db.sqlite3
    • Add ‘net duration’ field, for the officially measured time and use it for calculations if available.
    • Create django manage command to fill some base data: $ ./ fill_basedata
    • speedup by deactivating some django debug toolbar panels
  • 26.06.2018 - v0.4.0:

    • combine track filters with statistic views
    • NEW: GPX info (See length, point count and Average distance in meters between the points)
    • NEW: Display GPX metadata
    • Add ‘creator’ to every track and use it as changelist filter
    • remove Streetmap image generated via geotiler
    • Speedup by using a cache for gpxpy instances
  • 23.06.2018 - v0.3.0:

    • Start adding statistics (See screenshot above)
    • add weather information from to every track
  • 21.06.2018 - v0.2.0:

    • Display elevations, heart_rates and cadence_values if available
    • Add kilometer markers to OpenStreetMap
  • 15.06.2018 - v0.1.1:

    • a few bugfixes
  • 15.06.2018 - v0.1.0:

    • Render interactive OpenStreetMap track map with Leaflet JS
  • 12.06.2018 - v0.0.4:

    • Better Events model
    • GPX error handling
    • more tests
    • Bugfix for Python 3.5 (Geotiler needs Python 3.6 or later)
  • 12.06.2018 - v0.0.3:

    • display min/average/max heart rate
    • use autotask to generate the MAP in background
  • 31.05.2018 - v0.0.2:

    • generate SVG ‘icon’ from GPX track
  • v0.0.1 - 30.05.2018

    • Just create a pre-alpha release to save the PyPi package name ;)


The whole thing is based on many excellent projects. Especially the following:


Note: this file is generated from README.creole 2021-01-17 13:16:44 with "python-creole"

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-for-runners, version 0.12.0
Filename, size File type Python version Upload date Hashes
Filename, size django_for_runners-0.12.0-py3-none-any.whl (944.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-for-runners-0.12.0.tar.gz (883.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page