Skip to main content
This guide walks you through setting up PostHog for local development. You’ll be able to run the full stack including Django, React, PostgreSQL, ClickHouse, and Redis.

​
Prerequisites

1

System Requirements

  • macOS or Linux (Windows via WSL2)
  • 16GB RAM minimum (32GB recommended)
  • 20GB free disk space
  • Docker Desktop (for infrastructure services)
2

Required Tools

Install these tools before proceeding:
  • Git - Version control
  • Docker - For PostgreSQL, ClickHouse, Redis
  • Node.js 18+ - Frontend tooling
  • Python 3.11+ - Backend runtime
  • pnpm - Package manager

​
Quick Start

The fastest way to get started is using the automated setup: 
# Clone the repository
git clone https://github.com/PostHog/posthog.git
cd posthog

# Start infrastructure services (PostgreSQL, ClickHouse, Redis)
docker compose -f docker-compose.dev.yml up -d

# Install dependencies
pnpm install
pip install -r requirements.txt

# Run database migrations
python manage.py migrate
python manage.py migrate_clickhouse

# Start the development server
./bin/start
The ./bin/start script uses mprocs to run all services in parallel. It will automatically install mprocs via Homebrew if not present.
PostHog will be available at:

​
Detailed Setup

​
1. Environment Setup

Flox provides a reproducible development environment: 
# Install flox (if not already installed)
curl -fsSL https://downloads.flox.dev/by-env/stable/install.sh | bash

# Activate the environment
cd posthog
flox activate
This automatically installs:
  • Python 3.11 with required packages
  • Node.js and pnpm
  • PostgreSQL and ClickHouse clients
  • All development tools

​
Option B: Manual Setup

If not using Flox, install dependencies manually: 
# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install [email protected] node@18 pnpm postgresql clickhouse

# Install Python packages
pip install uv
uv pip install -r requirements.txt

​
2. Infrastructure Services

Start PostgreSQL, ClickHouse, and Redis using Docker: 
# Start all services
docker compose -f docker-compose.dev.yml up -d

# Check service status
docker compose -f docker-compose.dev.yml ps

# View logs
docker compose -f docker-compose.dev.yml logs -f
Services started:
  • PostgreSQL on localhost:5432
  • ClickHouse on localhost:9000 (HTTP: 8123)
  • Redis on localhost:6379
  • Kafka on localhost:9092 (for event ingestion)
  • Object Storage (MinIO) on localhost:19000
If ports are already in use, you can modify them in docker-compose.dev.yml.

​
3. Database Setup

Initialize both PostgreSQL and ClickHouse:
1

Create PostgreSQL database

# Create database (first time only)
python manage.py migrate

# Create superuser
python manage.py createsuperuser
2

Initialize ClickHouse

# Run ClickHouse migrations
python manage.py migrate_clickhouse
3

Load test data (optional)

# Create demo team and data
python manage.py setup_dev

​
4. Environment Variables

Create a .env file for local configuration: 
# Copy example config
cp .env.example .env
Key environment variables: 
# .env
DEBUG=1
SECRET_KEY=your-secret-key-here

# Database
DATABASE_URL=postgres://posthog:posthog@localhost:5432/posthog

# ClickHouse
CLICKHOUSE_HOST=localhost
CLICKHOUSE_DATABASE=posthog
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=

# Redis
REDIS_URL=redis://localhost:6379/

# Object Storage
OBJECT_STORAGE_ENABLED=True
OBJECT_STORAGE_ENDPOINT=http://localhost:19000
OBJECT_STORAGE_ACCESS_KEY_ID=object_storage_root_user
OBJECT_STORAGE_SECRET_ACCESS_KEY=object_storage_root_password

​
5. Frontend Setup

Install and build frontend assets: 
# Install dependencies
pnpm install

# Build once
pnpm --filter=@posthog/frontend build

# Or run in watch mode
pnpm --filter=@posthog/frontend dev

​
Running PostHog

The bin/start script runs all services in parallel: 
./bin/start
This starts:
  • Django web server (port 8000)
  • Celery workers (background tasks)
  • Celery beat (scheduled tasks)
  • Frontend dev server (hot reload)
  • Plugin server (event processing)
  • Temporal worker (workflows)
Additional options: 
# Enable distributed tracing
./bin/start --tracing

# Use custom mprocs config
./bin/start --custom bin/mprocs-custom.yaml
Use Ctrl+A then K to navigate between services in mprocs. Press Q to quit all services.

​
Running Services Individually

For debugging or targeted development: 
# Start Django development server
python manage.py runserver 8000

​
Development Workflow

​
Auto-Detection of Flox Environment

If using Flox, commands are automatically wrapped: 
# Automatically uses flox if available
pytest

# Equivalent to:
flox activate -- bash -c "pytest"
Never use flox activate in interactive sessions - it hangs. The auto-detection handles this for you.

​
Code Formatting

# Format and lint Python code
ruff check . --fix
ruff format .

​
Hot Reloading

  • Frontend: Changes auto-reload at http://localhost:8000
  • Backend: Django auto-reloads on Python file changes
  • Styles: Tailwind CSS rebuilds automatically

​
Common Tasks

​
Create a New Product

# Bootstrap product structure
bin/hogli product:bootstrap your_product_name

# Verify structure
bin/hogli product:lint your_product_name

​
Generate API Types

When you change Django serializers, regenerate TypeScript types: 
bin/hogli build:openapi
This updates:
  • frontend/src/generated/core/api.ts
  • products/*/frontend/generated/api.ts

​
Create Database Migrations

# Auto-generate migration
python manage.py makemigrations

# Apply migrations
python manage.py migrate

​
Reset Database

# Drop and recreate PostgreSQL
docker compose -f docker-compose.dev.yml down -v
docker compose -f docker-compose.dev.yml up -d
python manage.py migrate
python manage.py migrate_clickhouse

​
Troubleshooting

If you see Address already in use errors:
# Find process using port
lsof -i :8000

# Kill the process
kill -9 <PID>

# Or change the port in docker-compose.dev.yml
Ensure Docker services are running:
# Check service status
docker compose -f docker-compose.dev.yml ps

# Restart services
docker compose -f docker-compose.dev.yml restart
Clear caches and reinstall:
# Clear pnpm cache
pnpm store prune

# Remove node_modules
rm -rf node_modules frontend/node_modules

# Reinstall
pnpm install
If using Flox:
# Rebuild environment
flox activate -- bash -c "pip install -r requirements.txt"
Without Flox:
# Reinstall with uv
uv pip install -r requirements.txt --force-reinstall

​
Next Steps

Testing

Learn how to run and write tests

Contributing

Contribute code to PostHog

Build docs developers (and LLMs) love

Get started for freeTalk to us