This post is written specifically for myself and those who have issues with running Heroku locally in Windows. To be even more exact, this post is for those users who wish to run a nginx + php-fpm server for PHP applications such as Wordpress with PHP Buildpack in a Windows environment with the use of command line heroku local. I will explain why we need Windows Subsystem for Linux (WSL) in a bit.

If you are having issues setting up the environment, please read along. I am sure it will be beneficial for you to solve the issues on your end 😋. Let's go!


So, you want to deploy app to Heroku. You have installed all the necessary tools and packages, such as Heroku, Composer, etc. You have managed to pull and push the app to Heroku platform without any problem. It's all good.

Here's the thing. You want to develop the app locally but heroku local doesn't seem to work in Windows environment, so you decided to use WSL to run the PHP application in a Linux environment.

You have set up nginx, php-fpm, mysql and all that in the WSL, there are some other configuration stuff that you have already taken care of, which is also wonderful.

Now, the application can run on local system smoothly, but for about 1 out of 5 of the requests, the page will stuck there forever until connection timeout is set.

You are wondering: what is the reason causing this random request failures? It cannot be predicted on when and how it will happen. You search over the Internet, people have suggested to check on the mysql configuration file my.ini, configuring options such as bind-address, max_connections, max_allowed_packet and so on. Not sure if that helps, but you have tried. Nope. The issue is still there.

You thought it might be the mysql that is installed in WSL is not compatible with Windows, so you remove the mysql in WSL and reinstall it in Windows. It doesn't seem to solve the issue either.

You almost give up searching for solution. Out of the blue, you come across something seems to be very promising:

It is regarding to why the nginx + php-fpm won't work in WSL and how to solve this sort of bug in Windows. All the time spent of researching did not go into waste. You tried modifying those related config files for both nginx and php-fpm, but it didn't seem to fix the issue yet.

You decided to start debugging from the beginning. You found out that the startup script did not read the config files in those default configuration folders but rather it reads from its custom config file and also generate config file on the fly. You apply those recommended fixes and finally, your PHP application can run properly in Windows!


Alright, alright. Enough with the talk. Here's the solution:

  1. Navigate to your-current-folder\vendor\heroku\heroku-buildpack-php\conf\nginx and modify the heroku.conf.php file.
    NOTE: it is the heroku.conf.php file, NOT the heroku.conf as the heroku.conf will be generated from heroku.conf.php on the fly.
  2. Modify the file and add the following lines at the end of the file (inside location block):
		# default handling of .php
		location ~ \.php {
			# remove this line below, as we will not be using it
            # try_files @heroku-fcgi @heroku-fcgi;
			include fastcgi_params;
			fastcgi_buffering off; # This must be here for WSL as of 11/28/2018
			fastcgi_split_path_info ^(.+\.php)(/.*)$;
			fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
			fastcgi_param PATH_INFO $fastcgi_path_info if_not_empty;
			fastcgi_param SERVER_NAME $host;			

  1. Navigate to your-current-folder\vendor\heroku\heroku-buildpack-php\conf\php and modify the php file:
    NOTE: I believe if your running php version is 7 or above, there will be a folder named "7", and nested with the sub-version number, such as "3" or "4" depending on your php version. In my case, my current running php is 7.4, so the path to edit the file php-fpm.conf is at your-current-folder\vendor\heroku\heroku-buildpack-php\conf\php\7\4.

  2. Look for the line says listen = /tmp/heroku.fcgi.${PORT}.sock, replace it with the following:

# listen = /tmp/heroku.fcgi.${PORT}.sock
listen =

That should be all! Try to run heroku local again in WSL, all this issue is finally resolved!


Aren't you getting annoyed by these error messages?


You can easily remove them by changing one line in the php-fpm.conf. Try to locate the log_level and change it to the following:

# log_level = warning
log_level = alert

Tadaa! No more irrelevant logs on the terminal!

I hope this post will be a great help for you! See ya!

Post was published on , last updated on .

Like the content? Support the author by!