Skip to main content

​
Overview

This guide walks you through setting up a complete Kolibri development environment. By the end, you’ll have Python, Node.js, all dependencies installed, and be ready to run the development server.
Direct development on Windows is not supported. If you’re using a Windows machine, please set up your development environment using WSL (Windows Subsystem for Linux).

​
Prerequisites

Before starting, you’ll need:
  • Git and Git LFS
  • Terminal/command line access
  • Internet connection for downloading dependencies

​
Git and GitHub Setup

1

Install Git

Install and configure Git on your computer. Try this interactive tutorial if you need practice with Git.
2

Create GitHub Account

Sign up for GitHub if you don’t have an account already.
3

Fork the Repository

Fork the main Kolibri repository. This makes it easier to submit pull requests later.
4

Install Git LFS

Important: Install and set up Git Large File Storage. This is required for managing large files in the repository.
Register your SSH keys on GitHub to avoid repeatedly entering your password.

​
Clone the Repository

Clone your Kolibri fork to your local machine (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 Learning Equality repository as an upstream remote: 
git remote add upstream [email protected]:learningequality/kolibri.git
git fetch --all
git checkout -t upstream/develop

​
Python Setup

Kolibri requires Python 3.9 or higher (but not 3.14 or above). pyenv allows you to manage multiple Python versions easily. This is the highly recommended approach. 
# Install pyenv using Homebrew
brew update
brew install pyenv

# Add pyenv to your shell configuration
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile
echo 'eval "$(pyenv init --path)"' >> ~/.bash_profile

# Reload your shell
source ~/.bash_profile
Install a compatible Python version: 
pyenv install 3.9.9
Never modify your system’s built-in version of Python. Always use pyenv or a package manager to install separate Python versions.

​
Create a Virtual Environment

Virtual environments isolate project dependencies and prevent conflicts.
You can use pyenv-virtualenv, virtualenv, venv, or any other virtual environment tool. The instructions below use pyenv-virtualenv.
Create and activate a virtual environment: 
# Create virtual environment
pyenv virtualenv 3.9.9 kolibri-py3.9

# Activate the virtual environment
pyenv activate kolibri-py3.9
To deactivate later: 
pyenv deactivate
Keep your virtual environment activated for all remaining setup steps. Never install project dependencies using sudo pip install ...

​
Environment Variables

Set required environment variables before running Kolibri.

​
Required: KOLIBRI_RUN_MODE

This variable is required and filters development work out of usage statistics: 
export KOLIBRI_RUN_MODE="dev"
Add this to your ~/.bash_profile or ~/.bashrc to make it permanent: 
echo 'export KOLIBRI_RUN_MODE="dev"' >> ~/.bash_profile

​
Optional: KOLIBRI_HOME

Set this if you want to run multiple Kolibri versions simultaneously: 
export KOLIBRI_HOME="/path/to/kolibri/data"

​
Install Python Dependencies

With your virtual environment active and inside the kolibri directory: 
# Required dependencies
pip install -r requirements.txt --upgrade
pip install -r requirements/dev.txt --upgrade
pip install -e .

# Optional (for testing and documentation)
pip install -r requirements/test.txt --upgrade
pip install -r requirements/docs.txt --upgrade
The --upgrade flags can usually be omitted to speed up installation on subsequent runs.

​
Node.js and pnpm Setup

Kolibri requires Node.js 20.x for frontend development.

​
Install Node.js with nodeenv

The nodeenv tool (installed with Python dependencies) allows you to use specific Node.js versions: 
# Ensure your Python virtual environment is active
nodeenv -p --node=20.19.0
npm install -g pnpm

​
Install JavaScript Dependencies

pnpm install

​
Database Setup

Initialize the Kolibri database: 
kolibri manage migrate

​
Pre-commit Hooks (Required)

Pre-commit hooks are strongly recommended and ensure code quality before committing.
Always run this command after cloning the repository. If you don’t use pre-commit hooks, your code will likely fail CI checks on pull requests.

​
Install Pre-commit

pre-commit install
This enables automatic code formatting and linting on every commit.

​
Using Pre-commit

When you commit changes:
  1. Run git commit -m "Your message"
  2. Pre-commit runs checks automatically
  3. If checks fail:
    • Many issues are auto-fixed (formatting, etc.)
    • Review the auto-fixed files
    • Stage the fixed files: git add <files>
    • Re-run the commit
  4. Once all checks pass, the commit succeeds
To manually run all checks: 
pre-commit run --all-files
Run this before creating a pull request to ensure all files pass checks.

​
Running the Development Server

You’re ready to run Kolibri!

​
Quick Start (Frontend + Backend)

Build frontend assets and start the Django server: 
pnpm run devserver
Access Kolibri at http://127.0.0.1:8000/

​
Hot Reload Mode (Faster Development)

For faster frontend development with automatic reloading: 
pnpm run devserver-hot
Some functionality (like right-to-left language support) is broken when hot-reload is enabled.

​
Build Specific Plugins Only

To save resources, build only specific plugins: 
# Watch only the Learn plugin
pnpm run devserver-hot learn

# Build core and Learn plugin only
pnpm run devserver core,learn

​
Separate Servers (Backend Development)

If working mainly on backend code, run servers separately: Terminal 1 - Django devserver: 
pnpm run python-devserver
Terminal 2 - Frontend watcher: 
pnpm run frontend-devserver

​
Load Sample Data

​
Import Content

Import the Kolibri QA channel (~350MB) for testing:
  1. Go to http://127.0.0.1:8000/
  2. Navigate to Device > Channels
  3. Import with token: nakav-mafak

​
Generate Test Users

Auto-generate sample users, classes, and data: 
kolibri manage generateuserdata

​
Editor Configuration

Kolibri includes an .editorconfig file for consistent code formatting. Install the EditorConfig plugin for your editor:
  • Vue.js - Syntax highlighting and support
  • ESLint - JavaScript linting
  • Prettier - Code formatting
  • stylelint - CSS/SCSS linting

​
Vue.js Development Tools

Install Vue.js devtools (Legacy) browser extension for debugging.
Kolibri uses Vue 2, so install the “Legacy” version of Vue devtools, not the latest version.

​
Next Steps

Your development environment is ready! Here’s what to explore next:

Frontend Development

Learn Vue.js patterns, Design System, and composables

Backend Development

Understand Django, ValuesViewset, and API patterns

Testing

Write tests with pytest and Jest

Plugin Development

Create your first Kolibri plugin

​
Troubleshooting

​
Node Sass Binding Error

If you get “Node Sass could not find a binding” error: 
npm rebuild node-sass

​
Pre-commit Issues with Git Clients

If pre-commit fails with alternative Git clients (like GitUp): 
pre-commit uninstall

​
Database Migration Errors

If migrations fail, ensure:
  • Your virtual environment is active
  • Python dependencies are installed
  • KOLIBRI_RUN_MODE is set

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us