Skip to main content

​
Prerequisites

Before you begin, ensure you have:
  • Git with Git LFS installed
  • Python 3.9+ (but below 3.14) - we recommend using pyenv
  • Node.js 20.19.x - installed via nodeenv (shown below)
  • Terminal/Command Line access
Direct development on Windows is not supported. If you’re using Windows, set up your development environment using WSL (Windows Subsystem for Linux).

​
Quick Setup

Follow these steps to get Kolibri running locally:
1

Fork and Clone the Repository

First, fork the Kolibri repository on GitHub, then clone your fork:
# Replace $USERNAME with your GitHub username
git clone [email protected]:$USERNAME/kolibri.git
cd kolibri
Initialize Git LFS and configure git blame:
git lfs install
git config blame.ignoreRevsFile .git-blame-ignore-revs
Add the upstream remote to track Learning Equality’s repository:
git remote add upstream [email protected]:learningequality/kolibri.git
git fetch --all
git checkout -t upstream/develop
2

Set Up Python Virtual Environment

Create and activate a virtual environment using pyenv-virtualenv:
# Create a virtual environment (using Python 3.9.9 as example)
pyenv virtualenv 3.9.9 kolibri-py3.9

# Activate the virtual environment
pyenv activate kolibri-py3.9
If you don’t have pyenv installed, see the full installation guide for alternative methods like venv, virtualenv, or pipenv.
3

Set Required Environment Variable

Set the KOLIBRI_RUN_MODE environment variable (required for development):
export KOLIBRI_RUN_MODE="dev"
Add this to your ~/.bash_profile or ~/.zshrc to make it permanent:
echo 'export KOLIBRI_RUN_MODE="dev"' >> ~/.bash_profile
This variable:
  • Filters your development work out of usage statistics
  • Enables special testing behaviors
  • Must be set to a non-empty string
4

Install Python Dependencies

Install all required Python packages:
pip install -r requirements.txt --upgrade
pip install -r requirements/dev.txt --upgrade
pip install -e .
This installs:
  • Django 3.2.25 and Django REST Framework
  • Morango (synchronization framework)
  • Development tools (pre-commit, tox, ipdb)
  • All other dependencies from requirements/base.txt
5

Install Node.js and JavaScript Dependencies

Use nodeenv (installed with Python dependencies) to set up Node.js:
# Install Node.js 20.19.0 in the Python virtual environment
nodeenv -p --node=20.19.0

# Install pnpm globally
npm install -g pnpm

# Install JavaScript dependencies
pnpm install
This sets up:
  • Webpack build system
  • Vue.js and related frontend libraries
  • Jest testing framework
  • Development tools (ESLint, Prettier, etc.)
6

Set Up Pre-commit Hooks

Enable pre-commit hooks to ensure code quality:
pre-commit install
Pre-commit hooks are strongly recommended. They catch the same issues that CI checks will flag, saving you time on pull requests.
The hooks automatically:
  • Format Python code with Black
  • Format JavaScript/Vue with Prettier
  • Run linters (Flake8, ESLint, Stylelint)
  • Check for common errors
7

Initialize the Database

Create the SQLite database and run migrations:
kolibri manage migrate
You should see output showing migrations being applied:
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  Applying kolibriauth.0001_initial... OK
  ...
8

Start the Development Server

Launch both the Django backend and webpack frontend server:
pnpm run devserver
This single command:
  • Starts the Django development server on port 8000
  • Runs webpack in watch mode to build frontend assets
  • Auto-reloads when you make code changes
The first build takes several minutes as webpack compiles all frontend assets. Subsequent rebuilds are much faster.
Once you see:
Kolibri running on: http://127.0.0.1:8000/
Open your browser to http://127.0.0.1:8000/
9

Import Sample Content (Optional)

To test with real educational content, import the Kolibri QA channel:In the web interface:
  1. Complete the setup wizard
  2. Navigate to Device > Channels
  3. Click Import with token
  4. Enter token: nakav-mafak
  5. Select resources and import (~350MB)
Or generate sample users programmatically:
kolibri manage generateuserdata
This creates test users, classes, and assignments for development.

​
Verify Your Setup

To confirm everything is working: 
# Run a quick Python test
pytest kolibri/core/auth/test/test_permissions.py -k test_admin_can_delete_membership
If all tests pass, you’re ready to start developing!

​
Development Workflow

​
Running the Dev Server

Choose the command that fits your workflow: 
# Full devserver (Django + webpack watch)
pnpm run devserver

# With hot module replacement (faster rebuilds)
pnpm run devserver-hot

# Watch only specific plugins (faster, uses less resources)
pnpm run devserver-hot learn  # Only rebuild the Learn plugin
pnpm run devserver core,learn  # Rebuild core and Learn plugin
Hot reload mode breaks some functionality like right-to-left language support. Use regular devserver for testing RTL languages.

​
Running Separate Servers

For backend-focused work, build frontend once then run Django alone: 
# Terminal 1: Build frontend assets once
pnpm run build

# Terminal 2: Run Django devserver
pnpm run python-devserver
Or run them in separate terminals for full control: 
# Terminal 1: Django server
pnpm run python-devserver

# Terminal 2: Webpack watcher
pnpm run watch

​
Testing

# Run all tests
pytest

# Run specific test file
pytest kolibri/core/auth/test/test_permissions.py

# Run specific test by name
pytest kolibri/core/auth/test/ -k test_admin_can_delete

# Run with coverage
pytest --cov=kolibri

​
Common Issues and Solutions

This is expected! Pre-commit auto-fixes many issues:
  1. Review the changes pre-commit made
  2. Stage the fixed files: git add <files>
  3. Commit again: git commit -m "Your message"
The commit will succeed once all checks pass.
Rebuild node-sass for your current environment:
npm rebuild node-sass
Another Kolibri instance or process is using port 8000:
# Find the process
lsof -i :8000

# Kill it (use PID from above)
kill -9 <PID>

# Or use a different port
kolibri start --port=8001
Try resetting your database (development only!):
# Find your KOLIBRI_HOME
kolibri manage shell -c "from kolibri.utils.conf import KOLIBRI_HOME; print(KOLIBRI_HOME)"

# Remove the database
rm $KOLIBRI_HOME/db.sqlite3

# Re-run migrations
kolibri manage migrate
Limit which plugins are built:
# Only build/watch Learn plugin
pnpm run devserver learn

# Build multiple specific plugins
pnpm run devserver learn,coach,facility
This significantly reduces build time and memory usage.

​
Next Steps

Now that you have Kolibri running:

Architecture Overview

Understand Kolibri’s technical design

Contributing Guide

Learn the development workflow

Testing Guide

Write and run tests

Design System

Explore reusable UI components

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us