Skip to main content
This guide walks you through setting up a complete Bench development environment for building and testing Frappe applications.

​
Prerequisites

Before setting up Bench for development, ensure you have:
  • Python 3.10 or higher
  • Node.js 18 or higher
  • MariaDB/MySQL database server
  • Redis server
  • Git
  • A Unix-like operating system (Linux or macOS)
Bench is designed for development on Linux and macOS systems. For Windows, consider using WSL2 (Windows Subsystem for Linux).

​
Installing Bench

Install the Bench CLI tool using pip: 
pip3 install frappe-bench
Verify the installation: 
bench --version

​
Initializing a New Bench

1
Create a new bench directory
2
Initialize a new bench instance. This creates a directory with the Frappe framework and all necessary configuration:
3
bench init frappe-bench
4
This command will:
5
  • Create a new directory called frappe-bench
  • Set up a Python virtual environment in env/
  • Clone the Frappe framework into apps/frappe
  • Install Python and Node dependencies
  • Create configuration files for Redis, Procfile, and common site config
    • 6
    Use --frappe-branch to specify a particular Frappe version:
    bench init frappe-bench --frappe-branch version-15
    8
    cd frappe-bench
    9
    Create a new site
    10
    Create your first site where your applications will run:
    11
    bench new-site mysite.localhost
    12
    You’ll be prompted to set a MariaDB root password and an Administrator password for the site.
    13
    If your database is on a custom host or port, use:
    bench new-site mysite.localhost --db-host 192.168.1.100 --db-port 3307
    14
    Set the default site (optional)
    15
    To avoid using --site flag with every command:
    16
    bench use mysite.localhost

    ​
    Getting and Installing Apps

    1
    Download an app
    2
    Get apps from Git repositories:
    3
    bench get-app erpnext https://github.com/frappe/erpnext
    4
    For a specific branch:
    5
    bench get-app erpnext https://github.com/frappe/erpnext --branch version-15
    6
    For local development, you can create a soft link instead of cloning:
    bench get-app myapp --soft-link /path/to/local/myapp
    7
    Install the app on your site
    8
    bench --site mysite.localhost install-app erpnext

    ​
    Starting the Development Server

    Start all development processes using: 
    bench start
    This launches multiple processes defined in the Procfile:
    • web: Gunicorn web server (port 8000)
    • socketio: Real-time communication server (port 9000)
    • watch: Asset builder that watches for changes
    • schedule: Background scheduler
    • worker_short: Background worker for short jobs
    • worker_long: Background worker for long jobs
    • worker_default: Default background worker
    Access your site at http://localhost:8000 or http://mysite.localhost:8000Default credentials:
    • Username: Administrator
    • Password: The one you set during new-site

    ​
    Running specific processes

    To start only the web server: 
    bench serve
    To run in a different port: 
    bench serve --port 8080

    ​
    Developing Custom Apps

    1
    Create a new app
    2
    Generate a new Frappe application scaffold:
    3
    bench new-app myapp
    4
    You’ll be prompted for:
    5
  • App title
  • App description
  • Publisher name
  • Email
  • Icon
  • Color
    • 6
    Install your app
    7
    bench --site mysite.localhost install-app myapp
    8
    Start development with live reload
    9
    The bench start command automatically watches for changes in your Python and JavaScript files and reloads as needed.

    ​
    Development Best Practices

    ​
    Use Developer Mode

    Enable developer mode in your site for better debugging: 
    bench --site mysite.localhost set-config developer_mode 1
bench --site mysite.localhost clear-cache
    Developer mode provides:
    • Detailed error messages
    • Automatic reloading of Python code
    • Live Sass compilation
    • Access to developer console

    ​
    Managing Dependencies

    Update all Python dependencies: 
    bench setup requirements --python
    Update all Node dependencies: 
    bench setup requirements --node
    Install development dependencies: 
    bench setup requirements --dev

    ​
    Database Migrations

    After making changes to DocTypes, run: 
    bench --site mysite.localhost migrate

    ​
    Building Assets

    Manually build assets: 
    bench build
    Build for production: 
    bench build --production

    ​
    Running Tests

    Run tests for a specific app: 
    bench --site mysite.localhost run-tests --app myapp
    Run specific test: 
    bench --site mysite.localhost run-tests --app myapp --module myapp.tests.test_module

    ​
    Using the Bench Console

    Access a Python console with Frappe context: 
    bench --site mysite.localhost console

    ​
    Managing Multiple Sites

    List all sites: 
    bench --site all list-apps
    Backup a site: 
    bench --site mysite.localhost backup

    ​
    Troubleshooting Development Setup

    ​
    Port Already in Use

    If port 8000 is already in use: 
    # Find and kill the process
lsof -ti:8000 | xargs kill -9
    Or configure a different port in sites/common_site_config.json: 
    {
  "webserver_port": 8080
}

    ​
    Permission Errors

    Ensure proper ownership: 
    sudo chown -R $USER:$USER ~/frappe-bench

    ​
    Redis Connection Issues

    Restart Redis services: 
    bench restart

    ​
    Clear Cache and Rebuild

    For mysterious issues: 
    bench --site mysite.localhost clear-cache
bench build --force

    ​
    Development Workflow Summary

    1
    Daily workflow
    2
  • Start the development server: 
    bench start
  • Make changes to your app code
  • Changes are automatically detected and reloaded
  • Test your changes in the browser
  • Run migrations if needed: 
    bench --site mysite.localhost migrate
  • Commit your changes: 
    cd apps/myapp
git add .
git commit -m "Add new feature"

    • ​
    Next Steps

    Build docs developers (and LLMs) love

    Get started for freeTalk to us