Installation Guide

This comprehensive guide covers different installation methods for ERPNext, from quick Docker setups to production-ready deployments.

ERPNext requires Python >= 3.14 and Frappe Framework >= 17.0.0. Make sure your system meets these requirements.

Installation Methods

Choose the installation method that best fits your needs:

Docker

Best for: Quick testing, local developmentTime: 5 minutesDifficulty: Easy

Managed Hosting

Best for: Production without infrastructure managementTime: InstantDifficulty: None

Self-Hosted

Best for: Production with full controlTime: 30-60 minutesDifficulty: Advanced

Docker Installation

Docker provides the fastest way to get ERPNext running with minimal configuration.

Prerequisites

# Check Docker version (20.10+ required)
docker --version

# Check Docker Compose version (2.0+ required)
docker compose version

# Check Git installation
git --version

Docker Desktop must be running before proceeding. On Linux, ensure Docker service is active:

sudo systemctl status docker

Standard Docker Setup

Clone Frappe Docker Repository

git clone https://github.com/frappe/frappe_docker
cd frappe_docker

Launch Services

Use the provided compose file for a complete setup:

docker compose -f pwd.yml up -d

This starts:

MariaDB: Database server
Redis: Cache and queue
ERPNext: Application server
Nginx: Web server
Socketio: Real-time communication

Wait for Initialization

Monitor the setup process:

docker compose -f pwd.yml logs -f

Wait for: "Frappe site created successfully"

Access ERPNext

Open browser to http://localhost:8080Default Credentials:

Username: Administrator
Password: admin

ARM Architecture (Apple Silicon, ARM servers)

For ARM-based systems (M1/M2 Macs, ARM servers):

# Clone repository
git clone https://github.com/frappe/frappe_docker
cd frappe_docker

# Use ARM-specific images
export DOCKER_DEFAULT_PLATFORM=linux/arm64

# Build images for ARM
docker compose -f pwd.yml build

# Start services
docker compose -f pwd.yml up -d

See the Frappe Docker ARM documentation for detailed ARM setup instructions.

Docker Configuration Options

# Create docker-compose.override.yml
services:
  frontend:
    ports:
      - "8000:8080"  # Change to port 8000

Managed Hosting (Frappe Cloud)

The simplest production option with zero infrastructure management.

Features

One-Click Deployment: Launch ERPNext in minutes
Automatic Updates: Patches and upgrades handled automatically
Built-in Backups: Daily backups with point-in-time recovery
Monitoring: 24/7 uptime monitoring and alerts
SSL Certificates: Automatic HTTPS with Let’s Encrypt
Developer Tools: Git integration, staging sites, CI/CD

Getting Started

Create Account

Visit Frappe Cloud and sign up

Create Site

Choose region (US, EU, Asia, etc.)
Select ERPNext version
Pick a subdomain (e.g., yourcompany.frappe.cloud)

Configure and Deploy

Site is ready in 2-3 minutes with:

SSL certificate
Database backups
Email configuration

Try Frappe Cloud

Free trial available. Open-source platform maintained by the ERPNext team.

Self-Hosted Installation

For production deployments with full control over your infrastructure.

System Requirements

Minimum:

OS: Ubuntu 22.04 LTS, Debian 11+, or CentOS 8+
RAM: 4GB (8GB recommended for production)
CPU: 2 cores (4+ for production)
Disk: 40GB SSD
Python: 3.14+
Database: MariaDB 10.6+ or PostgreSQL 12+
Node.js: 18.x LTS
Redis: 6.x+

Recommended Production:

RAM: 16GB+
CPU: 4-8 cores
Disk: 100GB+ SSD (more for file attachments)
Separate database server for larger deployments

Using Bench (Recommended)

Bench is the official CLI tool for managing Frappe/ERPNext installations.

Install System Dependencies

On Ubuntu 22.04:

# Update system
sudo apt-get update
sudo apt-get upgrade -y

# Install dependencies
sudo apt-get install -y \
  python3.14 python3.14-dev python3.14-venv \
  python3-pip python3-setuptools \
  mariadb-server mariadb-client \
  redis-server \
  nginx \
  git \
  supervisor \
  libmariadb-dev \
  libpq-dev \
  curl

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Yarn
sudo npm install -g yarn

Configure MariaDB

Create configuration file /etc/mysql/mariadb.conf.d/50-server.cnf:

[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
max_allowed_packet = 256M

[mysql]
default-character-set = utf8mb4

Restart MariaDB:

sudo systemctl restart mariadb

Secure installation:

sudo mysql_secure_installation

Install Bench CLI

# Install bench using pip
sudo pip3 install frappe-bench

# Verify installation
bench --version

Initialize Frappe Bench

Create a new bench installation:

# Create bench directory
bench init frappe-bench --frappe-branch version-17

cd frappe-bench

This creates the bench directory structure:

frappe-bench/
├── apps/          # Frappe applications
├── sites/         # Site directories
├── config/        # Configuration files
├── logs/          # Log files
└── env/           # Python virtual environment

Create a New Site

# Create site (replace with your domain)
bench new-site erp.example.com \
  --admin-password 'SecurePassword123' \
  --mariadb-root-password 'YourMariaDBPassword'

Store the admin password securely. This is your ERPNext administrator account.

Install ERPNext App

# Download ERPNext
bench get-app erpnext --branch version-17

# Install on site
bench --site erp.example.com install-app erpnext

Installation takes 5-10 minutes and sets up:

Database schema
Default DocTypes
Module structure
Default workflows

Start Development Server

# Start bench for development
bench start

Access at http://localhost:8000

Production Setup with Bench

For production environments, configure Nginx, Supervisor, and SSL:

Setup Production Config

# Configure production settings
bench setup production [your-user]

# This configures:
# - Nginx as reverse proxy
# - Supervisor for process management
# - Redis for caching
# - Fail2ban for security

Enable Site

# Enable site in production
bench --site erp.example.com enable-scheduler
bench --site erp.example.com set-maintenance-mode off

Setup SSL Certificate

Using Let’s Encrypt:

# Install certbot
sudo apt-get install certbot python3-certbot-nginx

# Setup SSL
sudo bench setup lets-encrypt erp.example.com \
  --custom-domain erp.example.com \
  --email [email protected]

Configure Firewall

# Allow HTTP and HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Manual Configuration (Advanced)

For custom setups without using bench setup scripts:

# /etc/nginx/sites-available/erp.example.com
upstream frappe-bench {
    server 127.0.0.1:8000 fail_timeout=0;
}

server {
    listen 80;
    server_name erp.example.com;
    
    root /home/frappe/frappe-bench/sites;
    
    location / {
        proxy_pass http://frappe-bench;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    location /assets {
        try_files $uri =404;
    }
    
    location /files {
        try_files $uri =404;
    }
}

Development Setup

For contributing to ERPNext or developing custom apps.

Local Development Environment

Install Frappe Framework

# Initialize bench
bench init frappe-bench --frappe-branch develop
cd frappe-bench

# Create development site
bench new-site dev.localhost
bench use dev.localhost

Get ERPNext Source

# Clone ERPNext
bench get-app https://github.com/frappe/erpnext --branch develop

# Install on site
bench --site dev.localhost install-app erpnext

Enable Developer Mode

# Enable developer mode
bench --site dev.localhost set-config developer_mode 1

# Clear cache
bench --site dev.localhost clear-cache

Start Development Server

# Start bench with auto-reload
bench start

Access at: http://dev.localhost:8000

Developer Tools

# Watch for file changes and rebuild
bench watch

# Run tests
bench --site dev.localhost run-tests --app erpnext

# Access Python console
bench --site dev.localhost console

# Execute SQL queries
bench --site dev.localhost mariadb

# Rebuild search index
bench --site dev.localhost rebuild-search-index

Creating Custom Apps

# Create new custom app
bench new-app custom_app

# Install on site
bench --site dev.localhost install-app custom_app

# Directory structure
custom_app/
├── custom_app/
│   ├── config/
│   ├── public/
│   ├── templates/
│   └── www/
├── hooks.py
└── setup.py

Post-Installation

Essential Configuration

Configure Email

Settings → Email DomainSet up SMTP for sending emails:

Email server
Port (587 for TLS)
Authentication credentials
Enable SSL/TLS

Setup Backups

# Configure automatic backups
bench --site erp.example.com set-config \
  backup_frequency 'daily'

# Manual backup
bench --site erp.example.com backup \
  --with-files

Configure Print Settings

Settings → Print Settings

Add company letterhead
Set default print format
Configure PDF settings

System Settings

Settings → System Settings

Enable/disable modules
Set backup settings
Configure session timeout
Setup two-factor authentication

Performance Optimization

# Enable Redis cache
bench --site erp.example.com set-config \
  enable_realtime_updates 1

# Configure worker count (adjust for CPU cores)
bench setup supervisor --workers 4

# Enable gunicorn preload
bench setup supervisor --preload

# Restart services
sudo supervisorctl restart all

Maintenance

Updates and Upgrades

# Pull latest changes
cd frappe-bench
bench update --patch

# This updates:
# - Frappe framework
# - ERPNext app
# - Other installed apps

Monitoring

# View active workers
bench doctor

# Check site status
bench --site erp.example.com migrate-status

# Monitor logs
tail -f ~/frappe-bench/logs/*.log

# Check background jobs
bench --site erp.example.com show-pending-jobs

Troubleshooting

Common Installation Issues

Database Connection Issues

# Check MariaDB status
sudo systemctl status mariadb

# Test database connection
mysql -u root -p

# Grant permissions
GRANT ALL PRIVILEGES ON *.* TO 'frappe'@'localhost' 
IDENTIFIED BY 'password' WITH GRANT OPTION;
FLUSH PRIVILEGES;

Permission Issues

# Fix file permissions
cd ~/frappe-bench
sudo chown -R $USER:$USER .
sudo chmod -R 755 .

# Fix log directories
sudo chown -R $USER:$USER logs/

Port Conflicts

# Check what's using port 8000
sudo lsof -i :8000

# Kill process if needed
sudo kill -9 <PID>

# Change bench port
bench set-config http_port 9000

Clear Cache

# Clear site cache
bench --site erp.example.com clear-cache

# Clear Redis
redis-cli FLUSHALL

# Rebuild
bench build

Additional Resources

Bench Documentation

Complete guide to bench commands and configuration

Frappe Docker

Docker images and compose files for containerized deployments

Installation Forum

Get help with installation issues from the community

System Administration

Learn about maintaining and optimizing your installation

Need Professional Help?Consider hiring a Frappe Partner for production setup, migration, or custom development.

Getting Started

Core Modules

Setup & Configuration

Features

​Installation Guide

​Installation Methods

Docker

Managed Hosting

Self-Hosted

​Docker Installation

​Prerequisites

​Standard Docker Setup

​ARM Architecture (Apple Silicon, ARM servers)

​Docker Configuration Options

​Managed Hosting (Frappe Cloud)

​Features

​Getting Started

Try Frappe Cloud

​Self-Hosted Installation

​System Requirements

​Using Bench (Recommended)

​Production Setup with Bench

​Manual Configuration (Advanced)

​Development Setup

​Local Development Environment

​Developer Tools

​Creating Custom Apps

​Post-Installation

​Essential Configuration

​Performance Optimization

​Maintenance

​Updates and Upgrades

​Monitoring

​Troubleshooting

​Database Connection Issues

​Permission Issues

​Port Conflicts

​Clear Cache

​Additional Resources

Bench Documentation

Frappe Docker

Installation Forum

System Administration

Build docs developers (and LLMs) love

Installation Guide

Installation Methods

Docker Installation

Prerequisites

Standard Docker Setup

ARM Architecture (Apple Silicon, ARM servers)

Docker Configuration Options

Managed Hosting (Frappe Cloud)

Features

Getting Started

Self-Hosted Installation

System Requirements

Using Bench (Recommended)

Production Setup with Bench

Manual Configuration (Advanced)

Development Setup

Local Development Environment

Developer Tools

Creating Custom Apps

Post-Installation

Essential Configuration

Performance Optimization

Maintenance

Updates and Upgrades

Monitoring

Troubleshooting

Database Connection Issues

Permission Issues

Port Conflicts

Clear Cache

Additional Resources