Skip to main content

​
Overview

This guide will walk you through creating your first Frappe environment using Bench. You’ll learn how to initialize a bench, create a site, install apps, and start development.
Before starting, make sure you have installed Bench on your system.

​
Step 1: Initialize a Bench

A bench is a directory that contains the Frappe framework, apps, and sites.
1

Create a new bench

Initialize a new bench instance:
bench init frappe-bench
This command will:
  • Create a frappe-bench directory
  • Set up a Python virtual environment
  • Clone the Frappe framework
  • Install Python dependencies
  • Setup basic configuration files
bench init [bench-name] [OPTIONS]

Options:
  --frappe-branch BRANCH    Clone specific Frappe branch (e.g., version-15)
  --python PATH             Specify Python executable (default: python3)
  --dev                     Enable developer mode
  --skip-assets            Don't build assets during init
  --apps-path PATH         JSON file with apps to install after init
2

Navigate to bench directory

cd frappe-bench
Explore the directory structure:
ls -la
You’ll see:
apps/          # Frappe framework and other apps
config/        # Configuration files
env/           # Python virtual environment
logs/          # Log files
sites/         # Sites directory (empty for now)
Procfile       # Process definitions for development
Important: All subsequent bench commands must be run from within the bench directory (frappe-bench), except for bench init.

​
Step 2: Create Your First Site

Sites are individual Frappe instances with their own database and configuration.
1

Create a new site

bench new-site mysite.local
You’ll be prompted for:
  • MySQL root password: Your database root password
  • Administrator password: Password for the Frappe Administrator user
$ bench new-site mysite.local
MySQL root password: 
Administrator password: 
Re-enter administrator password: 

Installing frappe...
Creating database...
Creating tables...
Adding default doctypes...

*** Scheduler is disabled ***
2

Configure local DNS (Development only)

For local development, add your site to /etc/hosts:
echo "127.0.0.1 mysite.local" | sudo tee -a /etc/hosts
Or edit manually:
sudo nano /etc/hosts
Add this line:
127.0.0.1 mysite.local
3

Set site as default (Optional)

If you have multiple sites, set one as default:
bench use mysite.local
This allows running site-specific commands without the --site flag.

​
Advanced Site Options

# Connect to remote database
bench new-site mysite.local \
  --db-host 192.168.1.100 \
  --db-port 3306

​
Step 3: Install Apps

Apps extend Frappe with additional functionality. Let’s install ERPNext as an example.
1

Get the app

Download and setup an app in your bench:
bench get-app erpnext
This clones the ERPNext repository from GitHub and installs its dependencies.
# From GitHub (short form)
bench get-app erpnext

# From full GitHub URL
bench get-app https://github.com/frappe/erpnext

# From specific branch
bench get-app erpnext --branch version-15

# From local path
bench get-app /path/to/local/app

# From custom git repository
bench get-app https://github.com/mycompany/custom-app.git
2

Install app on site

Install the app on your site:
bench --site mysite.local install-app erpnext
This process:
  • Creates database tables for the app
  • Runs migrations
  • Installs app fixtures and demo data
  • Builds and installs frontend assets
$ bench --site mysite.local install-app erpnext

Installing erpnext...
Updating DocTypes...
Updating customizations for Address...
Creating default records...

*** Scheduler is disabled ***
3

Verify installation

List installed apps:
bench --site mysite.local list-apps
Expected output:
frappe
erpnext

​
Common Apps

ERPNext

Complete ERP system for businesses
bench get-app erpnext

HRMS

Human Resource Management System
bench get-app hrms

Payments

Payment gateway integrations
bench get-app payments

Custom App

Your own Frappe application
bench new-app my-app

​
Step 4: Start Development Server

Launch all required services for development.
1

Start the bench

bench start
This starts multiple processes:
  • web: Gunicorn web server (port 8000)
  • socketio: Real-time communication server
  • watch: Watches and auto-builds frontend assets
  • schedule: Background job scheduler
  • worker: Background job workers (short, long, default)
$ bench start

14:23:45 system           | redis_cache.1 started (pid=12345)
14:23:45 system           | redis_queue.1 started (pid=12346)
14:23:45 system           | redis_socketio.1 started (pid=12347)
14:23:46 system           | web.1 started (pid=12348)
14:23:46 system           | socketio.1 started (pid=12349)
14:23:46 system           | watch.1 started (pid=12350)
14:23:46 system           | schedule.1 started (pid=12351)
14:23:46 system           | worker_short.1 started (pid=12352)
14:23:46 system           | worker_long.1 started (pid=12353)
14:23:46 system           | worker_default.1 started (pid=12354)

14:23:47 web.1            | Booting worker with pid: 12348
14:23:47 web.1            | Started server on port 8000
2

Access your site

Open your browser and navigate to:
http://mysite.local:8000
Or use localhost:
http://localhost:8000
If you have multiple sites, specify the site in URL:
http://mysite.local:8000
3

Login

Use these credentials:
  • Username: Administrator
  • Password: The password you set when creating the site
You should see the Frappe desk interface.
4

Stop the server

Press Ctrl+C in the terminal to stop all processes.

​
Development Server Options

bench start --no-prefix

​
Common Workflows

​
Creating Additional Sites

# Create second site
bench new-site secondsite.local

# Install apps on specific site
bench --site secondsite.local install-app erpnext

# List all sites
bench list-sites

​
Managing Multiple Apps

# Get multiple apps
bench get-app erpnext
bench get-app hrms
bench get-app payments

# Install apps on a site
bench --site mysite.local install-app erpnext
bench --site mysite.local install-app hrms

# Uninstall app from site
bench --site mysite.local uninstall-app payments

# Remove app from bench entirely
bench remove-app payments

​
Database Operations

# Backup site
bench --site mysite.local backup

# Backup with files
bench --site mysite.local backup --with-files

# Restore from backup
bench --site mysite.local restore /path/to/backup.sql.gz

# Drop site (with confirmation)
bench drop-site mysite.local

​
Running Console

# Python console with Frappe context
bench --site mysite.local console

# MariaDB console
bench --site mysite.local mariadb

​
Troubleshooting

Check /etc/hosts file:
cat /etc/hosts | grep mysite.local
Should show:
127.0.0.1 mysite.local
Check if bench is running:
# In another terminal
curl http://localhost:8000
Find and kill the process using port 8000:
# Find process
lsof -i :8000

# Kill it
kill -9 [PID]
Or use a different port:
bench set-config -g http_port 8001
bench start
Ensure MariaDB is running:
sudo systemctl status mariadb
sudo systemctl start mariadb
Test connection:
mysql -u root -p
Reset the administrator password:
bench --site mysite.local set-admin-password newpassword
Clear cache and rebuild:
bench --site mysite.local clear-cache
bench build --app frappe
Reinstall dependencies:
bench setup requirements
Or for specific app:
bench pip install -e apps/[app-name]

​
Next Steps

Now that you have a working bench setup:

Explore Commands

Learn about all available Bench commands

Production Setup

Deploy your bench to production with NGINX and SSL

Create Custom App

Build your own Frappe application

Configuration

Configure bench and site settings

​
Quick Reference

​
Essential Commands

# Initialize bench
bench init [bench-name]

# Create site
bench new-site [site-name]

# Get app
bench get-app [app-name] [git-url]

# Install app
bench --site [site-name] install-app [app-name]

# Start development
bench start

# Update bench
bench update

# Backup site
bench --site [site-name] backup

# List sites
bench list-sites

# List apps
bench --site [site-name] list-apps
For a complete command reference, visit the Commands section.

Build docs developers (and LLMs) love

Get started for freeTalk to us