Struggling to set up Frappe/ERPNext on Ubuntu 24.04 LTS? Many users face issues with dependencies, configurations, and installation errors. This guide simplifies the process, providing clear, step-by-step, copy-paste-ready instructions for a hassle-free setup.

Whether you’re new to ERP systems or upgrading to v15, follow this guide to install Frappe/ERPNext seamlessly.

Pre-requisites

Ensure that your system meets the following requirements before proceeding:

• Python 3.11+ (Ubuntu 24.04 comes with Python 3.12 by default)
• Node.js 18 LTS (installed via nvm, not apt — see Step 9)
• Redis 5+ (for caching and real-time updates)
• MariaDB 10.3.x+ / PostgreSQL 9.5+ (for database-driven applications)
• Yarn (JavaScript dependency manager, activated via Corepack — see Step 10)
• Pip 20+ (Python dependency manager)
• wkhtmltopdf 0.12.6.1 with patched Qt (needed for PDF generation with headers/footers — the plain apt package does not have patched Qt, see Step 11)
• Cron (for scheduled jobs, backups, etc. — installed by default on Ubuntu Server)
• NGINX (only needed if you’re setting up a production site — not covered in this dev-setup guide)

Note — Ubuntu 24.04 default versions differ from Frappe’s minimums: Python ships as 3.12 and MariaDB ships as 10.11. Both are newer than Frappe’s documented minimums (Python 3.11 / MariaDB 10.3) and work fine — just be aware a few my.cnf options from older MariaDB guides (innodb-file-format, innodb-large-prefix) were removed in 10.3+ and will crash mysqld if you still have them. Step 7 below uses the current, correct settings.

Step-by-Step Installation

Step 1: Install Git

$ sudo apt-get update

$ sudo apt-get install git

Step 2: Install Python Development Tools

$ sudo apt-get install python3-dev

Step 3: Install Setuptools and Pip

$ sudo apt-get install python3-setuptools python3-pip

Step 4: Install a Python Virtual Environment

$ sudo apt install python3.12-venv

Ubuntu 24.04 ships Python 3.12 by default — if python3 --version shows something different on your system, swap python3.12-venv for the matching python3.X-venv package.

Step 5: Install MariaDB

$ sudo apt-get install software-properties-common

$ sudo apt install mariadb-server

$ sudo systemctl status mariadb

$ sudo mysql_secure_installation

Follow the prompts to set a root password and lock down the default install (remove anonymous users, disable remote root login, remove the test database).

Step 6: Install MySQL/MariaDB Development Files

$ sudo apt-get install libmysqlclient-dev

Step 7: Configure MariaDB for Frappe

Edit the MariaDB configuration file:

$ sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

Add the following settings:

[server]
user = mysql
pid-file = /run/mysqld/mysqld.pid
socket = /run/mysqld/mysqld.sock
basedir = /usr
datadir = /var/lib/mysql
tmpdir = /tmp
lc-messages-dir = /usr/share/mysql
bind-address = 127.0.0.1
query_cache_size = 16M
log_error = /var/log/mysql/error.log

[mysqld]
innodb-file-per-table = 1
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4

Modernized from the classic Frappe install guide: older versions of this guide also set innodb-file-format=barracuda and innodb-large-prefix=1. Both options were removed in MariaDB 10.3+ (Barracuda is the only format now, and the “large prefix” behavior is just the default) — on Ubuntu 24.04’s MariaDB 10.11, leaving them in will make mysqld refuse to start with an “unknown variable” error. The config above is the current, correct version.

Save and exit (Ctrl+X, then Y, then Enter), then restart MariaDB:

$ sudo systemctl restart mariadb

Step 8: Install Redis

$ sudo apt-get install redis-server

Step 9: Install Node.js via nvm

Don’t install Node from apt — Ubuntu’s repo version lags behind, and nvm lets you pin the exact version Frappe needs without touching your system Node.

$ sudo apt-get install curl

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

$ source ~/.bashrc

$ nvm install 18

$ nvm alias default 18

$ node -v

nvm alias default 18 matters — without it, nvm install 18 only applies to your current terminal session, and a fresh shell (or a reboot) silently falls back to no Node at all, which shows up later as a confusing bench failure.

Step 10: Activate Yarn via Corepack

Modern Node ships Corepack, so there’s no need to apt install npm separately or install Yarn globally — just enable it:

$ corepack enable

$ corepack prepare yarn@stable --activate

$ yarn -v

Step 11: Install wkhtmltopdf (Patched Qt Build)

The wkhtmltopdf package in Ubuntu’s default repo is not the patched-Qt build Frappe needs for PDF headers/footers — install the official patched release directly instead:

$ sudo apt-get install xvfb libfontconfig libxrender1 libjpeg-turbo8 fontconfig

$ wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.jammy_amd64.deb

$ sudo apt install ./wkhtmltox_0.12.6.1-3.jammy_amd64.deb

On a non-amd64 host (e.g. ARM), grab the matching package from the wkhtmltopdf releases page instead.

Step 12: Install Frappe Bench

$ sudo -H pip3 install frappe-bench --break-system-packages

$ bench --version

--break-system-packages is required on Ubuntu 24.04 — Python 3.12 blocks system-wide pip install by default (PEP 668) to protect apt-managed packages, and this flag explicitly opts in.

Step 13: Initialize Frappe Bench

$ bench init frappe-bench --frappe-branch version-15

$ cd frappe-bench/

$ bench start

Leave this running in its own terminal — it’s the dev server. Open a new terminal tab for the remaining steps.

Step 14: Create a Site in Frappe Bench

$ bench new-site localhost

Once it finishes, open http://localhost:8000 in your browser to access the site.

Step 15: Install ERPNext

$ bench get-app erpnext --branch version-15

$ bench --site localhost install-app erpnext

$ bench start

Conclusion

Congratulations! You’ve successfully installed Frappe/ERPNext v15 on Ubuntu 24.04 LTS. You can now start configuring your ERPNext instance to suit your business needs — set up your company, chart of accounts, and first users from the onboarding wizard that appears on first login.

This guide covers a local development setup. If you’re moving to production, you’ll want bench setup production, an NGINX reverse proxy, and proper site backups — happy to help with that directly if you’d rather not manage it yourself.

If you run into trouble during installation, get in touch — our ERPNext implementation and hosting services are built to take this setup (and everything after it) off your plate.

FAQ

1. What if I face compatibility issues with MariaDB 10.11?

MariaDB 10.11 (Ubuntu 24.04’s default) works with Frappe v15 as long as you use the current my.cnf settings in Step 7 — the common failure is leftover innodb-file-format/innodb-large-prefix options from older guides, which were removed in 10.3+. Remove those lines and mysqld will start normally.

2. How do I access ERPNext after installation?

Navigate to http://localhost:8000 in your browser and log in with the admin credentials you set when running bench new-site.

3. How do I keep my installation updated?

Run the following from inside your bench directory to pull and apply the latest updates for your apps:

$ cd frappe-bench

$ bench update

4. bench start works, but a new terminal can’t find node or bench — why?

This almost always means nvm’s shell hook isn’t loaded in the new session, or nvm alias default was never set (Step 9). Run source ~/.bashrc in the new terminal, or just reopen the terminal entirely — new sessions should pick up the default Node version automatically after that.

5. Do I need NGINX for local development?

No — bench start runs its own development server on port 8000. NGINX (plus bench setup production) is only needed when you’re serving ERPNext to real users outside your own machine.