Install Frappe v16 and ERPNext v16 HRMS V16 Beta on Ubuntu/Debian

Kibet_Sang · November 18, 2025, 5:56pm

Step 1: Update Your System

Before installing anything, it’s important to update your system packages:

sudo apt-get update -y
sudo apt-get upgrade -y

Step 2: Create a User for Frappe

It’s recommended not to run Bench as root. Create a new user or use an existing one:

sudo adduser frappe_user
sudo usermod -aG sudo frappe_user
su - frappe_user
cd /home/frappe_user

If you prefer to use your existing user, just replace frappe with your username in the commands below.

Step 3: Install Dependencies

Install the essential packages required for Frappe and ERPNext:

sudo apt-get install git -y
sudo apt-get install python3-dev -y
sudo apt-get install python3-setuptools python3-pip -y
sudo apt install python3.13-venv -y
sudo apt-get install software-properties-common -y

Step 4: Install MariaDB

sudo apt install mariadb-server -y
sudo mariadb-secure-installation

During the setup, use these recommended options:

Enter current password for root: (press ENTER)
Switch to unix_socket authentication? Y
Change root password? Y
Remove anonymous users? Y
Disallow root login remotely? N
Remove test database? Y
Reload privilege tables? Y

Step 5: Configure MariaDB

Open the MariaDB configuration file:

sudo nano /etc/mysql/my.cnf

Add the following:

[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
[mysql]
default-character-set = utf8mb4

Restart MariaDB:

sudo service mysql restart

Step 6: Install Redis

sudo apt-get install redis-server -y

Step 7: Install Node.js and npm (latest stable)

Step 7a: Remove old versions (if any)

sudo apt remove nodejs npm -y
sudo apt autoremove -y

Step 7b: Update packages and install prerequisites

sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ca-certificates gnupg

Step 7c: Add NodeSource repository and install Node.js 22 LTS

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Verify installation:

node -v
npm -v

Step 7d: Install Yarn

sudo npm install -g yarn

Step 8: Install PDF Rendering Tools

sudo apt-get install xvfb libfontconfig wkhtmltopdf -y

Step 9: Install Frappe Bench and Ansible

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

-H ensures correct HOME directory and --break-system-packages is needed for Ubuntu 24+.

Step 10: Initialize Frappe Bench

For v16 beta, use the beta branch:

bench init frappe-bench --frappe-branch v16.0.0-beta.1

Switch to your bench folder:

cd frappe-bench

Fix permissions:

sudo chmod -R o+rx /home/$USER

Replace $USER with your frappe username if needed.

Step 11: Create a New Site

bench new-site yoursite_name

Enter MySQL root user: root or your user
MySQL root password: your MySQL password
Set Frappe admin password when prompted

Step 12: Get ERPNext and HRMS Apps

ERPNext v16 beta:

bench get-app --branch v16.0.0-beta.1 https://github.com/frappe/erpnext.git

HRMS v16 beta:

bench get-app --branch v16.0.0-beta.1 https://github.com/frappe/hrms.git

Step 13: Install Apps to Your Site

ERPNext:

bench --site yoursite.local install-app erpnext

HRMS:

bench --site yoursite.local install-app hrms

Set the current site

bench use yoursite_name

Step 14: Start Development Server

bench start

kdrsrsln · November 20, 2025, 4:39am

At step 10, first got this error

”Exception: pkg-config is not installed. Please install it before proceeding.
You can refer to Installation

ERROR: There was a problem while creating frappe-bench”

Rollbacked the changes, installed pkg-config and during next initialize got this error this time

Exception: Can not find valid pkg-config name.
Specify MYSQLCLIENT_CFLAGS and MYSQLCLIENT_LDFLAGS env vars manually
[end of output]

note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed to build ‘mysqlclient’ when getting requirements to build wheel
Error occured during app install: /home/frappe/frappe-bench/env/bin/python -m pip install --quiet --upgrade -e /home/frappe/frappe-bench/apps/frappe

OS → Fresh installed Ubuntu 24.

how to fix this?

Kibet_Sang · November 20, 2025, 5:36am

MariaDB Libraries
sudo apt install libmariadb-dev libmariadb-dev-compat -y

Install build tools
sudo apt install build-essential pkg-config -y

python development libs
sudo apt install python3-dev python3.12-venv python3.12-dev -y

check if okay here

pkg-config --libs mariadb
pkg-config --cflags mariadb

and pick up from step 10

GGR · November 27, 2025, 5:09am

abrefael · January 13, 2026, 7:48am

There was some talks about stopping the use of wkhtmltopdf altogether, and transferring to something like Puppeteer.
Am I wrong?

Kibet_Sang · January 13, 2026, 10:24am

Hi, yes, look at the updated steps Frappe & ERPNext v16 Installation Ubuntu 25

abrefael · January 15, 2026, 8:24am

I tried these steps, and yet:

Traceback (most recent call last):
  File "env/lib/python3.14/site-packages/pdfkit/configuration.py", line 35, in __init__
    with open(self.wkhtmltopdf) as f:
         ~~~~^^^^^^^^^^^^^^^^^^
FileNotFoundError: [Errno 2] No such file or directory: b''

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "apps/frappe/frappe/app.py", line 121, in application
    response = frappe.api.handle(request)
  File "apps/frappe/frappe/api/__init__.py", line 63, in handle
    data = endpoint(**arguments)
  File "apps/frappe/frappe/api/v1.py", line 40, in handle_rpc_call
    return frappe.handler.handle()
           ~~~~~~~~~~~~~~~~~~~~~^^
  File "apps/frappe/frappe/handler.py", line 53, in handle
    data = execute_cmd(cmd)
  File "apps/frappe/frappe/handler.py", line 86, in execute_cmd
    return frappe.call(method, **frappe.form_dict)
           ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "apps/frappe/frappe/__init__.py", line 1124, in call
    return fn(*args, **newargs)
  File "apps/frappe/frappe/utils/typing_validations.py", line 36, in wrapper
    return func(*args, **kwargs)
  File "apps/frappe/frappe/utils/print_format.py", line 239, in download_pdf
    pdf_file = frappe.get_print(
    	doctype,
    ...<6 lines>...
    	pdf_generator=pdf_generator,
    )
  File "apps/frappe/frappe/utils/print_utils.py", line 103, in get_print
    return get_pdf(html, options=pdf_options, output=output)
  File "apps/frappe/frappe/utils/pdf.py", line 99, in get_pdf
    filedata = pdfkit.from_string(html, options=options or {}, verbose=True)
  File "env/lib/python3.14/site-packages/pdfkit/api.py", line 72, in from_string
    r = PDFKit(input, 'string', options=options, toc=toc, cover=cover, css=css,
               configuration=configuration, cover_first=cover_first, verbose=verbose)
  File "env/lib/python3.14/site-packages/pdfkit/pdfkit.py", line 45, in __init__
    self.configuration = (Configuration() if configuration is None
                          ~~~~~~~~~~~~~^^
  File "env/lib/python3.14/site-packages/pdfkit/configuration.py", line 38, in __init__
    raise IOError('No wkhtmltopdf executable found: "%s"\n'
    ...<3 lines>...
                  'https://github.com/JazzCore/python-pdfkit/wiki/Installing-wkhtmltopdf' % self.wkhtmltopdf)
OSError: No wkhtmltopdf executable found: "b''"
If this file exists please check that this process can read it or you can pass path to it manually in method call, check README. Otherwise please install wkhtmltopdf - https://github.com/JazzCore/python-pdfkit/wiki/Installing-wkhtmltopdf

even though:

(I am using Firefox, though… perhaps this is the reason this happened).

Actually, same error in Chromium.

trustedcomputer · January 16, 2026, 11:40am

What is your OS? Debian Trixie? Ubuntu 24.04 LTS? Are you installing wkhtmltopdf at all or are you trying to go completely without it?

abrefael · January 16, 2026, 1:51pm

I am working in Trixie.
Trying to work without wkhtml2pdf completely.
it’s just that I don’t get it - there are many alternatives that can replace it and are still supported in newer systems (some are actually pure python based). Why is the frappe framework team still keep on using wkhtml2pdf?

trustedcomputer · January 16, 2026, 2:35pm

It’s been a long road for sure, but in v16 it’s finally getting replaced with chrome/chromium. However, it’s still brand new, so you should install wkhtmltopdf anyway to cover any edge cases and avoid a warning banner when you generate a PDF.

If you are in trixie, install the chromium-headless-shell package. Then, set the location in your configuration this way:

bench set-config -g chromium_path /usr/bin/chromium-headless-shell

After that, you can go into your print settings and set the PDF generator globally there. You can also go into individual print formats and set a custom PDF generator there as needed.