Skip to main content

Developing Karrio

Documentation for developers contributing to the Karrio code base.



The following steps need to be performed inside a terminal window (Windows user may prefer to use the Windows WSL).

  • Fork karrio on Github.

  • Clone the repository:

git clone[YOUR_USERNAME]/karrio.git
cd karrio


Setup a PostgreSQL database for the application.

docker-compose up -d db

Installation using Python

  • Setup a Python environment with all dependencies:
source ./scripts/


# installation

# activate environment
source ./scripts/
  • Apply database migrations, collect static assets:
karrio migrate
karrio collectstatic --noinput
  • Finally, create yourself an admin account:
karrio createsuperuser
  • Start the server:
karrio runserver

On windows, use instead of localhost:5002


git clone[YOUR_USERNAME]/karrio-dashboard.git
cd karrio-dashboard
  • Install node dependencies:
npm install
  • Setup environment variables:
cp .env.sample .env

On windows set up: NEXT_PUBLIC_KARRIO_API_URL=http://localhost:5002

  • Start the dashboard:
npm run dev


Working on Karrio SDK core and all extensions

  • Setting up Karrio SDK and all carrier extensions
cd karrio
. ./scripts/
  • Running all SDK tests
cd karrio

Working on a single carrier

  • Setup a Python environment with the dev dependencies
cd karrio

This will create and activate an isolated Python environment with the dev dependencies required to work on karrio.

  • Install an extension in dev mode
cd karrio
# pip install -e sdk/extensions/[carrier_extension]
pip install -e sdk/extensions/fedex
  • Running tests for a single extension
cd karrio
# python -m unittest discover -v -f sdk/extensions/[carrier_extension]/tests
python -m unittest discover -v -f sdk/extensions/fedex/tests

Working on karrio server

  • Setting up Karrio server
cd karrio
. ./scripts/
  • Running all server tests
cd karrio
  • Running tests on a single karrio server module
cd karrio
# karrio test --failfast karrio.server.[module].tests
karrio test --failfast karrio.server.manager.tests

Reset Karrio database for a fresh reinstall

cd karrio
# stop and remove the database container
docker-compose down

# start a fresh Postgres container
docker-compose up -d db

Backup your data

cd karrio
karrio dumpdata -e contenttypes -o [BACKUP_LOCATION_PATH]/data[VERSION].json
# e.g: karrio dumpdata -e contenttypes -o ../backup/data2022.10-3.json

Load dev data

cd karrio
karrio loaddata [BACKUP_LOCATION_PATH]/data[VERSION].json
# e.g: karrio loaddata ../backup/data2022.10-1.json


Make sure Docker and Docker Compose work before attempting to run Karrio. We won't be able to assist with your Docker installation.

Make sure you've read the warning about Windows 10 Home. Windows versions before Windows 10 are not officially supported.

If you encounter other problems, see Support.