Running a business without proper systems is like driving at night without headlights, you might be moving, but you cannot see what is coming. ERPNext fixes that. It is a powerful, open-source ERP platform that brings your finance, HR, inventory, CRM, and operations under one roof. And the best part? It is free to use.
However, getting ERPNext up and running on Ubuntu requires a clear, step-by-step approach. Whether you are a developer setting up a test environment, or a business exploring ERPNext services before committing to a full ERPNext implementation, this guide will walk you through every command and decision you need to make.
Why Ubuntu Is the Preferred OS for ERPNext
Ubuntu (22.04 LTS) is the gold standard for hosting ERPNext. It is stable, widely supported, and perfectly suited for the Frappe framework that powers ERPNext. Most ERPNext consultants and ERPNext solution companies recommend Ubuntu for production deployments.
Prerequisites Before You Begin
Before running a single command, make sure you have the following in place:
• A fresh Ubuntu 22.04 LTS server (minimum 4GB RAM, 40GB storage recommended for production)
• Root or sudo access to the server
• A domain name pointed to your server IP (for production with ssl)
• Basic familiarity with the Linux terminal
If you are still deciding whether ERPNext is the right fit, understanding how ERPNext compares to traditional ERP systems can help you make a more informed choice before committing to a full deployment.
Step 1: Update Your Ubuntu System
Always start with a clean, updated system. Open your terminal and run:
sudo apt update && sudo apt upgrade -y
This ensures your package list is fresh and all existing packages are at their latest versions, reducing compatibility issues down the road.
Step 2: Install Required Dependencies
ERPNext relies on several underlying technologies. Install them all with:
sudo apt install -y python3-dev python3-pip python3-setuptools python3-venv \
mariadb-server mariadb-client \
redis-server \
libmysqlclient-dev \
git curl wkhtmltopdf \
xvfb libfontconfig \
nodejs npm
A quick breakdown of what each does:
• Python 3 — the core language ERPNext runs on
• MariaDB — the database engine storing all your business data
• Redis — handles caching and background jobs for performance
• wkhtmltopdf — generates PDF reports and invoices
• Node.js & npm — builds the frontend assets
Step 3: Configure MariaDB
ERPNext needs a properly configured database. Run the secure installation wizard:
sudo mysql_secure_installation
When prompted, set a strong root password, remove anonymous users, and disallow remote root login. Next, open the MariaDB config file to tune it for ERPNext:
sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf
Add or update these values under the [mysqld] section:
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
sudo systemctl restart mariadb
Step 4: Install Bench CLI
Bench is the command-line tool that manages your Frappe/ERPNext environment. Think of it as the control centre for your entire setup.
sudo pip3 install frappe-bench
Verify the installation:
bench –version
Step 5: Initialise a New Bench
Now, create a new bench environment. This sets up the Frappe framework that ERPNext is built on:
bench init –frappe-branch version-15 frappe-bench
cd frappe-bench
💡 The –frappe-branch flag sets which version of Frappe to install. For ERPNext 15 (the current stable release in 2026), use version-15.
Step 6: Create a New Site
Each ERPNext installation runs as a “site” within the bench. Create your site with:
bench new-site your-domain.com
You will be prompted to enter your MariaDB root password and set the Administrator password for ERPNext. Choose a strong password, this is your system’s master key.
Step 7: Install the ERPNext App
Get the ERPNext app and install it on your site:
bench get-app –branch version-15 erpnext
bench –site your-domain.com install-app erpnext
This step may take several minutes depending on your server speed. Bench will download all required Python and JavaScript packages and compile the frontend.
Step 8: Enable Production Mode
For a production deployment, run the production setup command. This configures Nginx as a reverse proxy and sets up Supervisor to keep your ERPNext processes running:
sudo bench setup production your-linux-username
After this, your ERPNext should be live and accessible at your domain or server IP.
Post-installation configuration, custom module setup, and multi-department workflows are where most teams hit a wall and where partnering with an experienced ERPNext implementation company makes all the difference.
Step 9: Set Up SSL with Let’s Encrypt
Never run a production ERP system without HTTPS. Secure your site with a free ssl certificate:
sudo bench setup lets-encrypt your-domain.com
Follow the prompts. Bench will automatically configure Nginx with your SSL certificate and set up auto-renewal.
Common Installation Issues and Fixes
Even experienced ERPNext consultants run into these during setup:
1. MariaDB Connection Error
If ERPNext cannot connect to MariaDB, check that the user privileges are correctly granted. Run:
mysql -u root -p
GRANT ALL PRIVILEGES ON *.* TO ‘root’@’localhost’ IDENTIFIED BY ‘yourpassword’ WITH GRANT OPTION;
FLUSH PRIVILEGES;
2. Node Version Conflict
ERPNext 15 requires Node.js 18+. If you have an older version, use nvm to manage versions:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
3. wkhtmltopdf PDF Generation Failures
On headless servers, wkhtmltopdf needs Xvfb to work. Ensure it is installed and run:
export DISPLAY=:0
When to Upgrade or Migrate Your ERPNext
Installation is just the beginning. As your business grows, so does the complexity of your ERPNext environment — more users, more data, more custom workflows. At some point, a self-managed setup may no longer serve you well.
As your business grows, you may start noticing slowdowns, workarounds, and limits that signal it is time to think about whether you have outgrown your current ERPNext setup and what a proper migration looks like.
Knowing when to scale is as important as knowing how to install.
Conclusion
Installing ERPNext on Ubuntu is a very manageable process once you understand each step and what it does. From updating your system and configuring MariaDB, to setting up Bench and enabling production mode, every command has a clear purpose.
The main thing is to go one step at a time, verify each stage before moving on, and not skip the security steps like SSL configuration and database hardening. A properly installed ERPNext gives you a robust, scalable foundation to run your entire business.
If you would rather have professionals handle the setup, our team provides end-to-end ERPNext services from initial deployment and custom module development to ongoing support, tailored to your industry and the way your business actually operates.
