Skip to content
Get packs

Guide · Open source

How to use Frappe: install with Docker and build your first app

Updated · written with AI from the project's own documentation and checked against our catalogue data

Frappe is a full-stack web framework that uses Python and MariaDB on the server, with a tightly integrated client-side library. It is built for data-heavy business and internal applications, and it was made for ERPNext. This guide shows how to start a local Frappe instance with Docker, what you get out of the box, and where to go next.

Frappe Frameworkfrappe/frappe · ★ 11k · MIT

Quick start

  1. 1Install Docker tools. Make sure docker, docker-compose and git are installed on your machine.
  2. 2Clone the Docker setup repository. Run git clone on the frappe_docker repository to get the compose setup.
  3. 3Enter the directory. Change into the frappe_docker folder with cd.
  4. 4Start the containers. Run docker compose with pwd.yml in the background using the up -d flags.
  5. 5Open the site. After a couple of minutes, visit localhost port 8080 and sign in as Administrator.
  6. 6Explore document types. Use the list view, form view and Role Permission Manager to see how data and access are handled.

What Frappe is and who it is for

Frappe describes your data as document types. From those definitions the framework provides forms, list views, role-based permissions, a REST API and an admin interface, so you do not have to build those parts yourself.

The README says Frappe is not the first thing to learn if you are just starting web programming. It suits developers who are already comfortable with Python and JavaScript and who are building complex, data-heavy applications. For a small static site or a simple landing page, a simpler tool is a better fit.

  • Full-stack: front-end and back-end in one framework
  • Built-in admin interface for managing application data
  • Role-based permissions for users and roles
  • Automatically generated REST API for all models
  • Customizable forms and views using server-side scripting and client-side JavaScript
  • Report Builder for creating reports without code

Install Frappe with Docker

The quickest documented route is Docker. You need docker, docker-compose and git installed. The README points to the Docker documentation for details on setting up Docker itself.

Run the three commands below. After a couple of minutes, the site should be reachable on localhost port 8080.

  • Prerequisites: docker, docker-compose, git
  • Default login username: Administrator
  • Default login password: admin
  • For ARM-based machines, the README links to separate instructions in the Frappe Docker repository
git clone https://github.com/frappe/frappe_docker cd frappe_docker docker compose -f pwd.yml up -d

Log in and look around the admin interface

Once the containers are running, open the site on localhost port 8080 and sign in as Administrator. The README lists the default credentials shown above. Change them if the instance will be reused for anything beyond testing.

The README also mentions a list view, a form view and a Role Permission Manager. These are the screens you will use to inspect the data and the access rules.

Set up a local development environment

If you want to develop against the framework rather than just run it, the README describes a manual route. Its quickest option is an install script for bench, which installs dependencies such as MariaDB. The script creates new passwords for the Frappe Administrator user, the MariaDB root user and the frappe user, and saves them to ~/frappe_passwords.txt.

For a local repository setup, set up bench following the installation steps in the official docs, then start the server and create a site.

  • Install dependencies with the bench install script (see the bench repository)
  • Keep the generated passwords from ~/frappe_passwords.txt safe
  • Start the server with bench start
  • Create a site with bench new-site frappe.localhost
  • Open http://frappe.localhost:8000/app in your browser
bench start bench new-site frappe.localhost

Where to learn more

The README lists Frappe School for courses by the maintainers and the community, the official documentation, and a discussion forum where users and service providers answer questions. Frappe Cloud is a hosted option that handles installation, upgrades, monitoring and support.

  • Frappe School: frappe.school
  • Official documentation: docs.frappe.io/framework
  • Discussion forum: discuss.frappe.io
  • Frappe Cloud: frappecloud.com for managed hosting

What people use it for

  • Internal tools for tracking business data such as orders, inventory or requests
  • Business applications with role-based access, where different staff see different records
  • Admin dashboards for managing application data without building one from scratch
  • Backends that need a REST API generated from the data models

Frequently asked questions

Is Frappe free to use?

Frappe is released under the MIT licence, as stated in the repository. The MIT licence permits use under its terms; check the LICENSE file for the full text.

What do I need to install Frappe?

The Docker route requires docker, docker-compose and git. The manual bench route needs the dependencies its install script covers, such as MariaDB. The README states Frappe uses MariaDB on the server side.

What is the default login for Frappe?

The Docker setup described in the README uses the username Administrator and the password admin on localhost port 8080. Change these credentials before using the instance for anything real.

Is Frappe good for beginners?

The README says it is not the first thing to learn if you are beginning web programming. Beginners may do better with a simpler framework and return to Frappe once they know Python and JavaScript.

How does Frappe compare to Django?

Django is a general-purpose Python web framework. Frappe is built around document types and provides forms, permissions, a REST API and an admin interface for data-heavy applications out of the box. Choose based on whether you need those features built in.

Why is my Frappe site not loading on port 8080?

The README says the site should be accessible after a couple of minutes. Wait for the containers to finish starting, then check that Docker is running and that the containers started with docker compose -f pwd.yml up -d.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Frappe suits developers who already know Python and JavaScript and are building data-heavy business or internal applications that need permissions, an admin UI and a REST API. If you are learning web programming, want a small static site, or cannot run MariaDB, pick a simpler framework.

Install options & downloads