# Installation

# Server Requirements

Invoice Ninja has a few system requirements. Built on top of Laravel it requires a PHP and MySQL server at a minimum with the following version and extensions installed.


You need to setup this version completely from scratch. Do not attempt to overwrite your old version of Invoice Ninja (4.x.x) with this version as the two codebases are completely different.

  • PHP >= 7.3.x
  • bcmath extension
  • ctype extension
  • fileinfo extension
  • json extension
  • mbstring extension
  • openssl extension
  • PDO extension
  • tokenizer extension
  • xml extension
  • curl extension
  • zip extension
  • gmp extension
  • mysqli extension
  • MySQL / MariaDB Server

# Installing Invoice Ninja

Technically computers has a very helpful step by step guide on how to install Invoice Ninja V5 from scratch onto CentOS, you can access the guide here. If Ubuntu is more your flavour you can follow his awesome guide here

# Download pre built zip. (Advanced)

A prebuilt zip can be downloaded from our GitHub release page here. You will need to download the package which is appended with -release, download the file named invoiceninja.zip.

Unzip this file into the virtual host directory you have created.


Ensure the file permission have been set to the web server user. For example in Ubuntu this is www-data if you have configured a virtual host with a root directory of /var/www/html you would set the ownership like this.

sudo chown -R www-data:www-data /var/www/html
# Web server configuration

A sample NGINX configuration is provided below, it assumes you have PHP 7.4 installed with the PHP FPM extension installed

server {

listen 80;
server_name invoiceninja.test;
root /var/www/invoiceninja/public;
index index.php index.html index.htm;
client_max_body_size 20M;

gzip on;
gzip_types      application/javascript application/x-javascript text/javascript text/plain application/xml application/json;
gzip_proxied    no-cache no-store private expired auth;
gzip_min_length 1000;

location / {
    try_files $uri $uri/ =404;

if (!-e $request_filename) {
    rewrite ^(.+)$ /index.php?q= last;

location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php7.4-fpm.sock;

location ~ /\.ht {
    deny all;



Performance hint!

Enable gzip in your webserver configuration, this will dramatically improve the loading time of the application! Please see the above nginx configuration for a sample of how to load the components of the application with gzip.

# Database server configuration

Create a database on your MySQL compatible server and add a user that has full access to the database, database configuration is out of the scope of this article, more information can be found here

# Headless Chrome

Invoice Ninja currently relies on Headless Chrome to generate PDFs, you will need to install this by running the follow command from the project directory

npm install
# Cron configuration

Invoice Ninja relies heavily on the Laravel Scheduler, for this to operate it requires that a cron job to be configured, edit your crontab and enter the following record

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Navigate your browser to your installation domain name address with /setup appended ie, www.invoiceninja.test/setup from this page you will configure your database, mailserver and the primary account user, when completed, click Submit and the app will setup your application and redirect you to the login page

# Installation from git (Advanced)

For power users installing the app from Github can be done with the following steps

git clone https://github.com/invoiceninja/invoiceninja.git

git checkout v2

composer update

cp .env.example .env

npm i

php artisan key:generate

php artisan optimize
# Cron configuration

Invoice Ninja relies heavily on the Laravel Scheduler, for this to operate it requires that a cron job to be configured, edit your crontab and enter the following record

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Configure your virtual host, create a database and point your browser to http://your.domain.com/setup and follow the bouncing ball!

# Installing Invoice Ninja (Docker)

If you prefer to use Docker, we have a dedicated repository with detailed instructions on how to get started HERE

# Migrating from V4

Migration of your data from V4 to V5 is done via the Settings panel of V4. Navigate to Settings > Account Management and click on Start Migration

For the migration to be successful you will need to ensure the signup email address is the same between V4 and V5. It is not possible to cross migrate using different email address as part of your credentials

For further help with migrating please chat to us on our Forum or our Slack Channel


After migration you will want to ensure all of your balances are correct to do this from the command line enter the following command

php artisan ninja:check-data

The command will output errors and identify where balances are not matching.

# Currency Conversion

Invoice Ninja supports Open Exchange for currency conversion. Open Exchange currently provides a free tier which is suitable for daily updates of the exchange rates. Simply insert a Open Exchange API key into your .env file to enable exchange rate updates


Make sure to update your cache afterwards

php artisan optimize

# Phantom JS

If it is not possible to install npm/node you can use an PhantomJS Cloud to generate your PDFs. They currently provide 500 free PDFs per day, which may suit most users

To override the system generating its own PDFs, you will need to insert the following keys into your .env file


Once this has been done you'll need to refresh the config cache

php artisan optimize


For PhantomJS to work, your Invoice Ninja installation web address must be public, localhost installations or those on private networks won't be able to use PhantomJS Cloud

# Trouble shooting

# Erroneous data format for unserializing 'Symfony\Component\Routing\CompiledRoute'

The most common cause of this issue is running multiple version of PHP, if the caches are built with a different version of PHP you may see the above error as differing versions of PHP may not be interoperable on the same installation. Ensure you are running the same CLI and Web PHP version to prevent any errors

# Unable to connect to database after installation

You may need to restart the queue like this

php artisan queue:restart

# Nginx: 413 – Request Entity Too Large

This error indicated that the client_max_body_size parameter in NGINX is too small, you will need to edit your nginx config and increase the size

client_max_body_size 100M;

# PDFs not generating. Timeouts

This may be due to some packages in the underlying subsystem not being installed which causes headless chrome to fail. In the logs you may see an error such as

chrome: error while loading shared libraries: libX11-xcb.so.1: cannot open shared object file: No such file or directory

To fix this you will need to install packages to support xcb

sudo apt-get install gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget


If you are having troubles installing NPM/NODE you may want to consider using PhantomJS Cloud, instructions to implement this can be found here Phantom JS

# Using multiple versions of NPM / NODE

If you are running mulitple versions of Node/NPM you may want to specify path to the correct version. To enable this you will need to set the environment variables as follows in the .env file



After updating the .env file you will need to recache the configuration, the simplest way to do this is.

php artisan optimize
Last Updated: 9/3/2020, 9:16:43 PM