Installation

Set up Frappe Framework on your machine

Frappe Framework can be installed using Docker for quick setup, or manually for development. Choose the method that best fits your needs.

Docker installation (recommended for evaluation)

The fastest way to try Frappe Framework is using Docker. This method is perfect for evaluation and testing.

1. Install prerequisites

   Ensure you have Docker, Docker Compose, and Git installed on your system.

   # Verify installations
   docker --version
   docker compose version
   git --version
   

   Refer to Docker Documentation for installation instructions specific to your operating system.

2. Clone and start Frappe Docker

   git clone https://github.com/frappe/frappe_docker
   cd frappe_docker
   docker compose -f pwd.yml up -d
   

   The first run will take several minutes as Docker downloads and builds the necessary images.

3. Access your site

   After a couple of minutes, your site will be accessible at http://localhost:8080

   Default credentials:

   • Username: Administrator
   • Password: admin

   Change the default password immediately after first login!

ARM architecture (Apple Silicon)

If you’re running on ARM-based systems (like M1/M2 Macs), see the Frappe Docker ARM setup guide.

Manual installation (recommended for development)

For development work, install Frappe Framework using bench, the CLI tool that manages Frappe applications.

Manual installation requires familiarity with the command line and system administration. If you’re new to Frappe, start with Docker first.

Prerequisites

Before installing Frappe, ensure your system has:

System dependencies

• Python 3.14+ - Frappe requires Python 3.14 or later
• Node.js 20+ - For building frontend assets
• MariaDB 10.6+ - Primary database (PostgreSQL also supported)
• Redis - For caching and background jobs
• wkhtmltopdf - For PDF generation
• Git - For version control

Operating system support

Frappe works best on:

• Ubuntu 22.04 LTS (recommended)
• Debian 11+
• macOS (for development)
• WSL2 on Windows (for development)

Production deployments should use Ubuntu or Debian Linux.

Install using bench

1. Install bench

   Bench is the CLI tool for managing Frappe applications. The easiest way to install it is using the automated script:

   # Install bench and all dependencies
   sudo pip3 install frappe-bench
   

   For more control, visit the bench installation guide.

   The installation script will create new passwords for the MariaDB root user, Frappe user, and Administrator account. These are displayed during installation and saved to ~/frappe_passwords.txt.

2. Initialize a bench

   Create a new bench (a directory that contains your Frappe installation):

   bench init frappe-bench
   cd frappe-bench
   

   This command:

   • Creates a new directory frappe-bench
   • Clones the Frappe Framework repository
   • Sets up a Python virtual environment
   • Installs Python and Node.js dependencies

   This process can take 5-10 minutes depending on your internet connection.

3. Create a new site

   Sites in Frappe are multi-tenant installations. Each site has its own database and can have different apps installed:

   bench new-site frappe.localhost
   

   You’ll be prompted to set an administrator password. This creates:

   • A new database
   • Site configuration files
   • Administrator user account
4. Start the development server

   bench start
   

   This starts multiple processes:

   • Web server (port 8000) - Serves your application
   • SocketIO (port 9000) - Real-time communications
   • Redis - Cache and job queue
   • Background workers - Process jobs asynchronously

   Keep this terminal window open. The development server will automatically reload when you make changes to Python files.

5. Access your site

   Open your browser and navigate to:

   http://frappe.localhost:8000/app
   

   Login with:

   • Username: Administrator
   • Password: (the password you set in step 3)

   If frappe.localhost doesn’t work, you may need to add it to your /etc/hosts file:

   127.0.0.1 frappe.localhost
   

Database options

While MariaDB is the default and recommended database, Frappe also supports PostgreSQL and SQLite.

MariaDB (default)

bench new-site mysite.localhost

SQLite is only suitable for development and testing. Never use it in production.

Verify installation

Confirm your installation is working correctly:

# Check bench version
bench --version

# Check Frappe version
bench version

# List all sites
bench --site all list-apps

Common installation issues

Port already in use

If port 8000 is already in use, you can specify a different port:

bench start --port 8001

Database connection errors

Verify MariaDB is running and accessible:

sudo systemctl status mariadb

Check database credentials in sites/common_site_config.json

Node.js build errors

Clear the build cache and rebuild:

bench clear-cache
bench build

Permission errors

Ensure your user has proper permissions:

sudo chown -R $USER:$USER ~/frappe-bench

Development environment setup

For the best development experience, install these additional tools:

Python tools

# Install development dependencies
pip install frappe-bench[dev]

# Install pre-commit hooks
cd ~/frappe-bench/apps/frappe
pre-commit install

Next steps

Quick start

Build your first Frappe app

Architecture

Understand how Frappe works

Core concepts

Learn about DocTypes and Documents

Bench commands

Master the bench CLI

Getting help

If you run into issues:

• Check the installation troubleshooting guide
• Ask on the discussion forum
• Review GitHub issues

Production deployment: This guide covers development setup. For production deployments, see the production setup guide.