How to Install ERPNext
ERPNext is built on the Frappe Framework, and the bench tool is the standard way to install, configure, and manage both. The bench tool handles Python virtual environment creation, Node.js dependency installation, database migrations, asset compilation, and process management. Understanding that bench is the central management tool is important because nearly every administrative task, from creating a site to applying updates, goes through bench commands.
Prepare the Server
Start with a fresh Ubuntu 22.04 LTS server. Cloud VMs from providers like DigitalOcean, AWS, Hetzner, or Linode work well. For a small deployment (up to 20 users), a server with 2 vCPUs, 4 GB RAM, and 50 GB SSD storage is sufficient. For larger deployments, refer to the self-hosting guide for sizing recommendations.
Create a non-root user with sudo privileges. ERPNext should not be installed or run as root. The bench tool explicitly warns against running as root and may refuse certain operations. A common convention is to create a user named frappe, though any username works.
Update the system packages by running apt update followed by apt upgrade. Configure the firewall with ufw to allow SSH (port 22), HTTP (port 80), and HTTPS (port 443). Enable the firewall after confirming SSH access is allowed so you do not lock yourself out.
Install System Dependencies
ERPNext requires several system packages. Install the core dependencies: Python 3.10 or later (included in Ubuntu 22.04), python3-dev, python3-pip, python3-venv for virtual environment support, git, redis-server, curl, and software-properties-common.
Install Node.js 18 LTS using the NodeSource repository. Add the NodeSource apt repository, update the package list, and install nodejs. After installation, install yarn globally with npm since the Frappe build system uses yarn for JavaScript dependency management.
Install wkhtmltopdf, which ERPNext uses to generate PDF versions of invoices, reports, and print formats. The version from the Ubuntu repository often lacks the patched Qt WebKit that wkhtmltopdf needs for proper rendering. Download the specific version from the wkhtmltopdf releases page that matches your Ubuntu version and architecture.
Install additional Python build dependencies that pip needs to compile certain packages: libffi-dev, liblcms2-dev, libldap2-dev, libmariadb-dev, libsasl2-dev, libtiff5-dev, libwebp-dev, and rlwrap. These are build-time dependencies that pip uses when installing Python packages with C extensions.
Configure MariaDB
Install MariaDB 10.6 or later from the Ubuntu repository or the MariaDB official repository. After installation, run the mysql_secure_installation script to set a root password, remove anonymous users, disable remote root login, and remove the test database.
ERPNext requires specific MariaDB configuration settings. Edit the MariaDB configuration file (typically at /etc/mysql/mariadb.conf.d/50-server.cnf or a custom file in the conf.d directory) and add the following settings under the [mysqld] section: set the character set to utf8mb4, set the collation to utf8mb4_unicode_ci, set innodb_file_format to Barracuda, set innodb_file_per_table to 1, set innodb_large_prefix to 1, and set the default storage engine to InnoDB.
Also add settings under the [mysql] section to set the default character set to utf8mb4. Restart the MariaDB service after making these changes. These settings ensure ERPNext can store Unicode characters properly (including emoji in notes and communications) and use modern InnoDB features for table compression and large index prefixes.
Install Bench and Initialize
Switch to your non-root user account. Install the bench CLI tool by running pip3 install frappe-bench. This installs bench as a command-line tool available in your path.
Initialize a new bench directory by running bench init with a directory name, for example bench init frappe-bench. This command creates the directory structure, downloads the Frappe framework from GitHub, creates a Python virtual environment, installs Python dependencies, installs Node.js dependencies with yarn, and builds the frontend assets. The process takes several minutes depending on your server's internet connection speed.
Change into the newly created bench directory. Verify the installation by running bench start, which launches the development server on port 8000. You should see the Frappe framework login page in your browser at http://your-server-ip:8000. Stop the development server with Ctrl+C after confirming it works.
Install ERPNext and Create a Site
From within the bench directory, download the ERPNext application by running bench get-app erpnext. This clones the ERPNext repository from GitHub into the apps directory and installs its Python dependencies.
Create a new site by running bench new-site followed by your domain name, for example bench new-site erp.yourdomain.com. The command prompts for the MariaDB root password and creates a new database, runs all database migrations to create the required tables, and prompts you to set an administrator password. Remember this password, as it is used for the initial login.
Install ERPNext on the site by running bench install-app erpnext with the site name specified using the --site flag. This activates ERPNext's modules and runs its setup procedures. After installation, launch the development server again with bench start and log in with the administrator account. You should see the ERPNext setup wizard that walks through company creation, chart of accounts selection, and initial configuration.
Configure for Production
The development server is not suitable for production use. It handles requests sequentially, lacks process supervision, and does not serve static files efficiently. The bench tool includes a production setup command that configures the necessary services.
Run bench setup production with your Linux username as the argument. This command installs and configures Nginx as the web server and reverse proxy, sets up Supervisor (or systemd depending on your configuration) to manage the Gunicorn application server workers and the background job workers, creates the necessary configuration files, and enables the services to start automatically on boot.
After running the production setup, the site will be accessible on port 80 (HTTP). The bench tool generates Nginx configuration that proxies requests to the Gunicorn workers and serves static files (JavaScript, CSS, images) directly from the filesystem without involving the application server.
Verify the production setup by accessing your site in a browser using the server's IP address or domain name on port 80. Check that static assets load correctly (the page should be styled, not showing raw HTML), that login works, and that background jobs are processing (check the bench doctor output for status).
Set Up SSL and DNS
Before configuring SSL, point your domain's DNS A record to your server's public IP address. Wait for DNS propagation, which typically completes within a few minutes for new records, though it can vary depending on your DNS provider.
Once DNS is resolving to your server, set up SSL with Let's Encrypt by running bench setup lets-encrypt followed by your site name. This command installs Certbot if needed, obtains an SSL certificate from Let's Encrypt, configures Nginx for HTTPS, sets up HTTP-to-HTTPS redirection, and creates a cron job for automatic certificate renewal.
After SSL is configured, verify that your site loads correctly over HTTPS. Check that the certificate is valid by clicking the lock icon in your browser's address bar. Test that HTTP requests redirect to HTTPS. Confirm that the automatic renewal cron job is in place by checking the crontab for the renewal command.
The bench tool handles most of the complexity of installing ERPNext. The key requirements are a properly configured MariaDB instance with the correct character set and InnoDB settings, a non-root user account, and the system dependencies installed before starting. Once bench init and bench new-site complete successfully, the production setup and SSL configuration are largely automated.