By Sparsh in Frappe Framework — Dec 10, 2025

Frappe Development Environment: Local Setup for App Developers

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