Guide: Manual Install ERPNext on Ubuntu 16.xx & Debian v8 & 9

Hi All,

After doing a clean manual install for Ubuntu 16.xx & Debian v8 & 9 (Specifically Debian Stretch) to understand what some of the issues/errors that we all get, following is what I ended up with that solves some of issues that come up. If anyone comes across any issues and resolves them please add them to the steps here. This is not final and I expect it can be refined further.

NOTE: This of course could vary for everyone. But a few things to take into consideration

  1. Clean install on Ubuntu & Debian

  2. User is frappe with sudo privileges

  3. Replace apt with apt-get for ubuntu

  4. Also a good idea to check if you already have some of the items below installed simply do a -V or --version

  5. Installed on Virtualbox Virtual machines

  6. Debian specs
    NAME="Debian GNU/Linux" VERSION_ID="9" VERSION="9 (stretch)" ISO Image Used: debian-stretch-DI-rc2-amd64-netinst.iso

  7. Ubuntu Specs
    Description: Ubuntu 16.10 Release: 16.10 Codename: yakkety ISO Image Used: ubuntu-16.10-server-amd64.iso

Login As Root User or use SUDO

  1. apt upgrade
  2. apt update
  3. adduser frappe (not required if you have added the user during VM setup)
  4. usermod -aG sudo frappe
  5. apt install build-essential
  6. apt install software-properties-common
  7. apt-key adv --recv-keys --keyserver 0xF1656F24C74CD1D8
  8. apt install dirmngr
  9. apt install curl
  10. apt install mariadb-client mariadb-server Test the install: mysql -u root -p
  11. apt install nginx Test the install: http://[IP-NUMBER-OF-INSTALL_SERVER]
  12. curl -sL | sudo bash -
  13. apt install nodejs Test the install: node -v && npm -v
  14. apt install redis-server Test the install: redis-server -v
  15. apt install wkhtmltopdf
  16. apt install git-core (will be needed during installation of Bench, Frappe & ERPNext)
  17. apt install python-pip
  18. apt install libmysqlclient-dev and/or apt-get install libmariadbclient-dev / apt-get install python-mysqldb (This resolves the issue of Python not connecting to MariaDB MySQL)
  19. apt install libssl-dev
  20. pip install --upgrade setuptools
  21. pip install MySQL-python --no-use-wheel (Wheel does not have a MySQL-python module yet, so it will error if the -no-use-wheel is not flagged)
  22. apt install supervisor (needed for production mode)

Reboot server
Login as As frappe User

  1. git clone bench-repo
  2. sudo pip install -e bench-repo
  3. bench init frappe-bench && cd frappe-bench
  4. bench new-site site1.local
  5. bench start To Test Installation
  6. If there are issues in accessing the site @ http://[SERVER-IP:8000] do a bench reinstall

Reboot server
Login as As frappe User

  1. bench get-app erpnext
  2. bench --site site1.local install-app erpnext
  3. bench start
  4. bench setup production [frappe] to switch to production as this is develop

IMPORTANT: This is a pure manual install with nothing on the servers and its for that reason that there are many installs. I would highly recommend you use the easy install option as that is what I have successfully used numerous times. All in all this install took me about 7-8 hours to complete.

Cannot Move beyond the installation wizard
Best way to install stable version of ErpNext
Error Frappe Erpnext on ubuntu 14.04 installation
Stuck on "Sorry! We will be back soon.", after Verifying
How do I install ERPNext
Bench start with serveral errors
ERPNext setup on Antix Linux
[ARCHLINUX] [LXC containers] Installation troubleshooting
Manual Installation Problem
Python egg_info" failed with error code 1
Install ERPNext to default site failed
Have the Dev's come up an easy way to install the last stable v9?
Installing Erpnext on Ubuntu 16.04
ERPNext on a Raspberry Pi 3 with Debian 9
Pymysql.err "Can't connect to MySQL server on u'localhost"
Error after os upgrade Ubuntu 17.04
Install ERPNext on own domain
Got stuck in erpnext installation in ubuntu16.4 on vm
Failed to Run Command bench --site site1.local install-app erpnext
Easy Installation setup (production with nginx and supervisor) on previous version
Generating a Virtual Image... is that even possible?!?
ERPNext setup on Antix Linux
How to setup frappe in ubuntu 17.04
Issue during install of erpnext in ubunut 16.04
How do you install ERPNEXT on NGINX VHOST with custom Lemp Stack
Fresh install no tables in DB
Easy Installation setup (production with nginx and supervisor) on previous version
Installation on Debian in VM
No module named 'frappe'
Need help Setting up ERPnext for the first time
Install erpnext app cannot import module Process Statement Of Accounts
No luck using Easy Install Ubuntu 16.04 and 18.04
I'm a newbie, and I've got an issue with the install
Is there a "Easy Install" script for Debian 9
Redis socketio failing on new Debian9 ERPnext install

There’s an issue during the setup part and following seems to resolve it

1. bench reinstall
2. bench clear-cache
3. Ensure you have at least 2gb RAM allocated to the server
4. Commence install
5. Uncheck all checked boxes in User Setup section
6. Uncheck both "Add sample records & Setup a simple website for my organisation"

Good guide! But why are you doing manual install? when you can do easy install.

@johnskywalker , I’ve actually never did a manual install. This was an exercise to better understand what is involved and many it seems do manual installs because they have existing server and so forth.

Basically, wanted to know as well what it entails to do a manual install and the issues that arise from it.

Also hoping that by sharing the steps, it would reduce the posts about installation issues.

I have explained in the first part of the post.


This might also help the guys trying to troubleshoot their Debian Stretch installations. :sweat_smile:
Thanks, @saidsl! Nice guide. :slight_smile:

1 Like

@littlehera, Thanks, that’s the idea :slight_smile:

1 Like

Thankyou very much for the guide! After the first reboot, before point 1, you’re missing point 0:

git clone GitHub - frappe/bench: CLI to manage Multi-tenant deployments for Frappe apps bench-repo


Because we are using PIP sudo pip install -e bench-repo we don’t need to clone from git.

@saidsl, @johnskywalker, technical user prefers manual installation. The manual installation does not work well as the installation document requires update. For help in manual installation please refer to script bench/install_scripts/

You can release this as wiki in frappe/erpnext github


I will leave it to the team to include in frappe/erpnext github as I don’t have access.

I think some people do like manual install for the matters of control. or we can do installation gradually, stop in certain step and continue install in the next day. Easy install/ automated install required certain duration of time which is not everybody have it. Easy install is fully depending on uninterruptible power supply, internet connection which is absent sometimes.

Hi everyone,

When I execute this step [1] in tutorial, I get this error [2].

Can you help me please?

Thanks in advanced

bench init frappe-bench && cd frappe-bench

Checking connectivity… done.
(‘installing’, u’frappe’) frappe
INFO:bench.utils:frappe-bench/env/bin/pip install -q -e frappe-bench/apps/frappe --no-cache-dir
Command “/home/frappe/frappe-bench/env/bin/python -u -c “import setuptools, tokenize;file=‘/tmp/pip-build-ElvKtM/mysqlclient/’;f=getattr(tokenize, ‘open’, open)(file);‘\r\n’, ‘\n’);f.close();exec(compile(code, file, ‘exec’))” install --record /tmp/pip-sQbDVS-record/install-record.txt --single-version-externally-managed --compile --install-headers /home/frappe/frappe-bench/env/include/site/python2.7/mysqlclient” failed with error code 1 in /tmp/pip-build-ElvKtM/mysqlclient/
Traceback (most recent call last):
File “/usr/local/bin/bench”, line 11, in
load_entry_point(‘bench’, ‘console_scripts’, ‘bench’)()
File “/home/frappe/bench-repo/bench/”, line 40, in cli
File “/usr/local/lib/python2.7/dist-packages/click/”, line 722, in call
return self.main(*args, **kwargs)
File “/usr/local/lib/python2.7/dist-packages/click/”, line 697, in main
rv = self.invoke(ctx)
File “/usr/local/lib/python2.7/dist-packages/click/”, line 1066, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File “/usr/local/lib/python2.7/dist-packages/click/”, line 895, in invoke
return ctx.invoke(self.callback, **ctx.params)
File “/usr/local/lib/python2.7/dist-packages/click/”, line 535, in invoke
return callback(*args, **kwargs)
File “/home/frappe/bench-repo/bench/commands/”, line 19, in init
verbose=verbose, clone_from=clone_from)
File “/home/frappe/bench-repo/bench/”, line 56, in init
get_app(frappe_path, branch=frappe_branch, bench_path=path, build_asset_files=False, verbose=verbose)
File “/home/frappe/bench-repo/bench/”, line 76, in get_app
install_app(app=app_name, bench_path=bench_path, verbose=verbose)
File “/home/frappe/bench-repo/bench/”, line 107, in install_app
File “/home/frappe/bench-repo/bench/”, line 130, in exec_cmd
raise CommandFailedError(cmd)
bench.utils.CommandFailedError: frappe-bench/env/bin/pip install -q -e frappe-bench/apps/frappe --no-cache-dir

At this point the Easy Install script is NOT compatible with Debian 9 (Stretch) and it tells you that upfront when you try to use it. Hopefully that will change soon. I would like to switch to Debian9, but I am not willing to spend a whole day trying to get it to install manually.


1 Like


The issue seems to be with mysqlclient

error code 1 in /tmp/pip-build-ElvKtM/mysqlclient/

You need to be check with your install if you have all the related packages installed. Do a pip list to ensure that you have everything installed before starting with frappe & erpnext installation bench init frappe-bench && cd frappe-bench

For reference these are the packages running on:

Debian 9

appdirs (1.4.3) bench (4.1.0, /home/frappe/bench-repo) click (6.7) cryptography (1.7.1) enum34 (1.1.6) ez-setup (0.9) gitdb (0.6.4) GitPython (0.3.2rc1) honcho (1.0.1) idna (2.2) ipaddress (1.0.17) Jinja2 (2.9.6) keyring (10.1) keyrings.alt (1.3) MarkupSafe (1.0) meld3 (1.0.2) MySQL-python (1.2.5) mysqlclient (1.3.7) packaging (16.8) pip (9.0.1) psutil (5.2.2) pyasn1 (0.1.9) pycrypto (2.6.1) pygobject (3.22.0) PyMySQL (0.7.11) pyparsing (2.2.0) python-crontab (2.1.1) python-dateutil (2.6.0) pyxdg (0.25) requests (2.13.0) SecretStorage (2.3.1) semantic-version (2.6.0) setuptools (34.4.1) six (1.10.0) smmap (0.9.0) supervisor (3.3.1) virtualenv (15.1.0) wheel (0.29.0)

And these are the packages in Ubuntu 16.10

ansible ( appdirs (1.4.3) asn1crypto (0.22.0) bench (4.1.0, /home/frappe/.bench) cffi (1.10.0) click (6.7) cryptography (1.8.1) enum34 (1.1.6) gitdb (0.6.4) GitPython (0.3.2rc1) honcho (0.7.1) idna (2.5) ipaddress (1.0.18) Jinja2 (2.9.5) MarkupSafe (1.0) meld3 (1.0.2) MySQL-python (1.2.5) packaging (16.8) paramiko (2.1.2) pip (9.0.1) psutil (5.2.1) pyasn1 (0.2.3) pycparser (2.17) pycrypto (2.6.1) pyparsing (2.2.0) python-apt (1.1.0b5) python-crontab (2.1.1) python-dateutil (2.6.0) PyYAML (3.12) requests (2.13.0) semantic-version (2.6.0) setuptools (34.3.3) six (1.10.0) smmap (0.9.0) supervisor (3.3.1) virtualenv (15.1.0) wheel (0.29.0)

NOTE: I have not updated the installations since I did the guide above a few months back. But it should not impact the installation.

For anyone trying it on Debian 9.1 Clean /Server /VPS
This worked for me and with safer practice of Debian thatis without sudo permission for any user


adduser frappe (if not set initally)

take care to remove conflicting packages e.g. apache2-bin conflicts with nginx

apt install build-essential software-properties-common libssl-dev libmariadbclient-dev python-pip python-setuptools python-mysqldb mariadb-server dirmngr nginx git-core redis-server supervisor wkhtmltopdf

APT will not set ‘root’ PASSWORD in mariadb-server necessary for frappe/ERPnext

curl -sL | bash -

apt install nodejs


Login as As frappe User

git clone GitHub - frappe/bench: CLI to manage Multi-tenant deployments for Frappe apps bench-repo

su (super user/root passowrd)

pip install -e bench-repo

exit (exit superuser)

continue as frappe user

bench init frappe-bench (if bench command doesnt work rerun above pip install again)

bench new-site site1.local

bench start and test


If all goes well remove .cache folder from /root folder for safety

Hello @saidsl
I’ve been following your guide for manual installing, it worked just perfect until
bench --site site1.local install-app erpnext
It shows an error like this

frappe@erp:~/frappe-bench$ bench --site site1.local install-app erpnext

Installing erpnext…
Updating DocTypes for erpnext : [========== ]Traceback (most recent call last):
File “/usr/lib/python2.7/”, line 174, in runmodule_as_main
“main”, fname, loader, pkg_name)
File “/usr/lib/python2.7/”, line 72, in runcode
exec code in run_globals
File “/home/frappe/frappe-bench/apps/frappe/frappe/utils/”, line 94, in
File “/home/frappe/frappe-bench/apps/frappe/frappe/utils/”, line 18, in main
File “/home/frappe/frappe-bench/env/local/lib/python2.7/site-packages/click/”, line 722, in call
return self.main(*args, **kwargs)
File “/home/frappe/frappe-bench/env/local/lib/python2.7/site-packages/click/”, line 697, in main
rv = self.invoke(ctx)
File “/home/frappe/frappe-bench/env/local/lib/python2.7/site-packages/click/”, line 1066, in invoke
return processresult(sub_ctx.command.invoke(sub_ctx))
File “/home/frappe/frappe-bench/env/local/lib/python2.7/site-packages/click/”, line 1066, in invoke
return processresult(sub_ctx.command.invoke(sub_ctx))
File “/home/frappe/frappe-bench/env/local/lib/python2.7/site-packages/click/”, line 895, in invoke
return ctx.invoke(self.callback, **ctx.params)
File “/home/frappe/frappe-bench/env/local/lib/python2.7/site-packages/click/”, line 535, in invoke
return callback(*args, **kwargs)
File “/home/frappe/frappe-bench/env/local/lib/python2.7/site-packages/click/”, line 17, in new_func
return f(get_current_context(), *args, **kwargs)
File “/home/frappe/frappe-bench/apps/frappe/frappe/commands/”, line 24, in _func
ret = f(frappe._dict(ctx.obj), *args, **kwargs)
File “/home/frappe/frappe-bench/apps/frappe/frappe/commands/”, line 160, in install_app
installapp(app, verbose=context.verbose)
File “/home/frappe/frappe-bench/apps/frappe/frappe/”, line 141, in install_app
sync_for(name, force=True, sync_everything=True, verbose=verbose, reset_permissions=True)
File “/home/frappe/frappe-bench/apps/frappe/frappe/model/”, line 45, in sync_for
File “/home/frappe/frappe-bench/apps/frappe/frappe/modules/”, line 58, in import_file_by_path
ignore_version=ignore_version, reset_permissions=reset_permissions)
File “/home/frappe/frappe-bench/apps/frappe/frappe/modules/”, line 129, in import_doc
File “/home/frappe/frappe-bench/apps/frappe/frappe/model/”, line 219, in insert
File “/home/frappe/frappe-bench/apps/frappe/frappe/model/”, line 790, in run_post_save_methods
File “/home/frappe/frappe-bench/apps/frappe/frappe/model/”, line 666, in run_method
out = Document.hook(fn)(self, *args, **kwargs)
File “/home/frappe/frappe-bench/apps/frappe/frappe/model/”, line 887, in composer
return composed(self, method, *args, **kwargs)
File “/home/frappe/frappe-bench/apps/frappe/frappe/model/”, line 870, in runner
add_to_return_value(self, fn(self, *args, **kwargs))
File “/home/frappe/frappe-bench/apps/frappe/frappe/model/”, line 660, in
fn = lambda self, args, **kwargs: getattr(self, method)(args, **kwargs)
File “/home/frappe/frappe-bench/apps/frappe/frappe/core/doctype/doctype/”, line 203, in on_update
updatedb(, self)
File “/home/frappe/frappe-bench/apps/frappe/frappe/model/”, line 71, in updatedb
File “/home/frappe/frappe-bench/apps/frappe/frappe/model/”, line 148, in sync
File “/home/frappe/frappe-bench/apps/frappe/frappe/model/”, line 183, in create
engine=self.meta.get(“engine”) or ‘InnoDB’) % (, add_text))
File “/home/frappe/frappe-bench/apps/frappe/frappe/”, line 165, in sql
File “/home/frappe/frappe-bench/env/local/lib/python2.7/site-packages/MySQLdb/”, line 250, in execute
self.errorhandler(self, exc, value)
File “/home/frappe/frappe-bench/env/local/lib/python2.7/site-packages/MySQLdb/”, line 50, in defaulterrorhandler
raise errorvalue
mysqlexceptions.OperationalError: (1005, ‘Can't create table 1bd3e0294da19198.tabSupplier Scorecard Criteria (errno: 168 “Unknown (generic) error from engine”)’)

Things I did differently, out of manual installation guide above are

  • completely remove Apache2 with apt-get purge apache2*

  • I’m using official repository from MariaDB 10.2, Nginx and Node.js 8

  • added these in to my.cnf file, as instructed

character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
default-character-set = utf8mb4

  • Installed on Revoluzio Server, fresh VPS server with Ubuntu 16.04

Browsed hundreds of sites on Google, but found nothing specific about this MySQL error like stated above

(errno: 168 “Unknown (generic) error from engine”)')

Maybe, you could identify what I did wrong during the installation. Any help or information would be highly appreciated.


I can’t really pin point the exact issue, however, I would suggest you try out the following

bench update --reset
bench migrate 

Failing that you can try

bench reinstall

And then try and install ERPNext again

Hope this helps


Best article for a while…
I got these errors on Linux Mint 18.2 when installing MySQL-python with pip but “sudo apt-get install python-dev” resolves it.

_mysql.c:29:20: fatal error: Python.h: No such file or directory
 #include "Python.h"
compilation terminated.
error: command 'x86_64-linux-gnu-gcc' failed with exit status 1

Thank You @TurkerTunali

Glad to know its helping you.