Tips / Nginx

How to install HHVM + Nginx on Ubuntu 14.04 LTS

HHVM is a virtual machine created by Facebook engineers, it was built to support high traffic from PHP requests for the facebook requirements. It’s used ot execute PHP and Hack apps. The main difference between HHVM PHP and other PHP servers is the fact that HHVM compiles PHP into machine code for faster processing.

The only downside of HHVM is that it requires more RAM and CPU than other PHP engines like PHP-FPM, but it does make sense since it includes the compiling work that should use more resources than other solutions. Recommended minimum hardware for HHVM should be at least 2 CPU and 1GB RAM with SSD drives for production websites.

Let’s start with the fun stuff.

Installing HHVM and Nginx on Ubuntu 14.04


  • Ubuntu 14.04 running
  • Root access
  • 1GB RAM

Installing Nginx

Just to be sure, let’s stop apache in case it’s running:

service apache2 stop

Let’s install Nginx, add it to boot automatically and start the service:

apt-get install nginx
update-rc.d nginx defaults
service nginx start

Installing HHVM

Ubuntu 14.04 already has an official HHVM repo.
In order to install the HHVM repo you need to import the GnuPG public keys:

apt-key adv --recv-keys --keyserver hkp:// 0x5a16e7281be7a449

Install the repo:

add-apt-repository "deb $(lsb_release -sc) main"

Update the software database:

apt-get update

Install HHVM and add it to boot automatically:

apt-get install hhvm
update-rc.d hhvm defaults

Configuring HHVM

HHVM can be integrated with Nginx in a very easy way with a default script included in HHVM installation, it works for most default Nginx installations.

Warning: this HHVM integration will work on default Nginx installations without any PHP-FPM/FastCGI previous configuration.

Run this command as root:

sh /usr/share/hhvm/

What does this script does exactly?

Basically, this integration HHVM + Nginx integration script will add the default hhvm.conf configuration file (/etc/nginx/hhvm.conf) into the default Nginx server block configuration, located at /etc/nginx/sites-enabled/default.

What can I do if I already modified my Nginx or added a FastCGI configuration?

Then the solution is to add HHVM configuration manually, replacing your current FastCGI configuration.


nano -w /etc/nginx/sites-enabled/default

Add this HHVM configuration for PHP processing:

location ~ \.(hh|php)$ {
         fastcgi_keep_conn on;
         fastcgi_index index.php;
         fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
         include fastcgi_params;

By default HHVM is listening on port 9000 and allows you to parse hack and php files, as it is stated at the Nginx-HHVM configuration we used before.

Reload Nginx to apply changes:

service nginx restart

HHVM main configuration file

HHVM can be configured by editing the file server.ini:

nano -w /etc/hhvm/server.ini

You should see something like this:

; php options
pid = /var/run/hhvm/pid

; hhvm specific
hhvm.server.port = 9000
hhvm.server.type = fastcgi
hhvm.server.default_document = index.php
hhvm.log.use_log_file = true
hhvm.log.file = /var/log/hhvm/error.log
hhvm.repo.central.path = /var/run/hhvm/hhvm.hhbc

Explanation of each HHV directive

hhvm.server.port = 9000

This is the default port where HHVM is listening on localhost, you can change it as you need. If you need to change it to listen on a socket instead of system port, remove the hhvm.server.port variable and add this new one:


If you remove HHVM port and start using sockets you will also have to configure the fastcgi_pass variable located at /etc/nginx/hhvm.conf.


nano -w /etc/nginx/hhvm.conf

Set fastcgi_pass as you see below:

fastcgi_pass unix:/var/run/hhvm/hhvm.sock;

Save the file and reload Nginx:

service nginx restart
hhvm.server.type = fastcgi

This is the way HHVM server is executed, there are two types: FastCGI and Proxygen. FastCGI is the one we choose to run PHP separately from the web server. Proxygen on the other side, is a full web server build inside HHVM.

HHVM is considered for environments under heavy load so the first configuration change you can do is to make HHVM listen to a socket instead of a TCP port. Thus, the communication between Nginx and HHVM will require less CPU and memory.

hhvm.server.default_document = index.php

Is the default document that will be served if a page is not explicitly specified.

hhvm.log.use_log_file = true

Enables the default logging mechanism via the log file specified by hhvm.log.file

hhvm.log.file = /var/log/hhvm/error.log

The specified location of the HHVM error log file.

hhvm.repo.central.path = /var/run/hhvm/hhvm.hhbc

The path to the hhvm.hhbc file created when you compiled a repo-authoritative repo.
After configuring HHVM remember to restart to apply changes:

service hhvm restart


If your index.php doesn’t work properly after installing HHVM and Nginx, remember to set your index default files to parse index.php files first before any other like index.htm.

nano -w /etc/nginx/sites-enabled/default

And set index variable as you see below:

index index.php index.html index.htm

Reload Nginx to apply changes:

service nginx restart

Testing HHVM

Check if you can see the hhvm version:

/usr/bin/php --version

Output should be something like this:


If see the output from the old PHP, then run the follwing cmmand to point your php binary to HHVM:

/usr/bin/update-alternatives --install /usr/bin/php php /usr/bin/hhvm 60

Create a phpinfo file to check if Nginx can parse PHP files from HHVM

nano -w /usr/share/nginx/html/info.php

Paste this inside that file:


Finally, try to browse http://your.server.ip/info.php.

If everything is OK you should see the HHVM information:


As we’ve seen in this article, HHVM is a very powerful PHP server that can perform really well in terms of speed. Integrating HHVM and Nginx is an easy task too, for advanced and beginner users. However, remember that HHVM may not be the most suitable solution for all cases, remember that on with low hardware resources with less than 1GB of RAM and 2 CPUs it may be even slower than PHP-FPM daemon or mod_php. Try it and let us know your results.

Popular search terms:

  • debian 8 server configuration nginx hhvm
  • Does HHVM require more memory?
  • hhvm server
  • hhvm ubuntu

Esteban Borges

Linux Geek, Webperf Addict, Nginx Fan. CTO @Infranetworking