Frappe Development Environment: Local Setup for App Developers

Sparsh -

A step-by-step guide on how to set up local Frappe/ ERPNext development environment using frappe_docker and VS Code devcontainer for active development with hot-reload and debugging.

Who this is for: Developers who want a local Frappe dev environment to build and customize Frappe Apps within Frappe Framework.

OS Compatibility: This guide works for

  • macOS (Apple Silicon & Intel)
  • Linux (Ubuntu 22.04+)

Prerequisites Checklist

  • Docker Desktop (or Docker + docker-compose) running
  • VS Code and Dev Containers extension installed
  • Git, stable internet.
  • macOS M1/M2 users: For ARM arch, see note below

Step 1: Clone frappe_docker repo

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

Step 2: Copy vscode/ devcontainer examples

cp -R development/vscode-example development/.vscode                  

cp -R devcontainer-example .devcontainer
⚠️
New Bench updates uses uv as default tool. Also python 3.14 gives error with pypika library. This results in build failed errors with installer.py

For a quick solution, update docker-compose.yaml file to use bench:v5.27.0 on line number 45 inside /.devcontainer/docker-compose.yaml
frappe:
    image: docker.io/frappe/bench:v5.27.0

Open frappe_bench folder in VS Code.

code .

Step 3: Install Dev Containers extension (VS Code)

  • Install Dev Containers extension from Microsoft in VS Code

Extension Identifier: ms-vscode-remote.remote-containers

Step 4: Reopen in Container and Open a terminal

Open frappe_bench folder inside the dev container. Use the dialog box or access remote container menu at bottom left corner.

  • Reopen in Container
💡
If popup disappears, close and reopen the frappe_bench folder.

After opening folder in devcontainer, open up a New Terminal

Use Terminal > New Terminal or use shortcut: CTRL + SHIFT + `

Below commands expect you to be inside the devcontainer terminal.

To ensure it, terminal prompt should mount at: frappe@{identifier}:/workspace/development/

Step 5: Run ./installer.py (inside devcontainer)

./installer.py --verbose

--verbose flag is optional. Use it to watch installation progress.

💡
default site ends with .localhost. Run./installer.py --help for flags.

Step 6: Start bench (inside devcontainer)

cd frappe_bench
bench start

Done. Frappe Development for Developers. 🎉


Access your running instance at http://development.localhost:8000

Use default credentials:
user: administrator
pwd: admin

Points to remember:

⚠️
Network Security: Do not use default admin credentials on public networks.
  • Your live development environment lives here:
    /workspace/development/frappe-bench
  • Default database is MariaDB
  • development folder is ignored by git to prevent accidental commits
  • To build apps and reflect changes, enable Developer mode:
    bench --site development.localhost set-config developer_mode 1
  • After setting developer mode, clear the cache:
    bench --site development.localhost clear-cache
  • Frappe: One installation = many sites, each with own database