Introduction:
Firstly, I'd like to mention this is not an in depth tutorial on how to install Laravel, instead i address the common issues when trying to install Laravel with Composer on a Windows operating system and how to fix them to continue your installation.
As you may already know, installing Laravel successfully on a Windows operating system with the ability to further build & develop your project can be tricky, and a headache for some! This is due to the dependencies required to install and run Laravel and more commonly down to the issues with Windows OS and the PHP dependency manager 'Composer'.
If you have tried to install Laravel 5.x/6.x/7.x on Windows OS you may have encounters these errors. Please * Note * these errors will vary depending on your installation versions, any packages or tools you may already have installed and of course the time of you reading this.
The information i provide is both first hand examples from myself installing the tools and scripts show, and also online guides/documentation i have sourced to help create a working solution.
/ Composer :
"Laravel utilizes Composer to manage its dependencies. So, before using Laravel, make sure you have Composer installed on your machine." - Assuming you have composer already installed on your machine, if not visit GetComposer.org to install.
When following the Laravel 7.x online Documentation, the section '#Installing Laravel' prompts you to enter the following command (after installing Composer) to download and run the Laravel Installer:
' composer global require laravel/installer '
This is the first common issue encountered. Underneath that command, the documentation also says: "Make sure to place Composer's system-wide vendor bin directory in your $PATH so the laravel executable can be located by your system."
This is where first time or Windows users find it difficult to continue the installation. The directory is of course different depending on your OS, and for windows its slightly different than OS & GNU (Linux) systems:
- macOS: $HOME/.composer/vendor/bin
- GNU / Linux Distributions: $HOME/.config/composer/vendor/bin (or) $HOME/.composer/vendor/bin
- Windows: %USERPROFILE%\AppData\Roaming\Composer\vendor\bin
The documentation also says, you can use the following command to find Composers global installation path: (after installing composer)
' composer global about '
(The directory is the first line displayed after you run the command.)
/ Vendor Bin $PATH :
After reading several websites to find a common guide, the website PhotoGabble displays a the most simple and very useful instructions on how to place Composers System-wide vendor bin directory in your $PATH.
As explained in their guide, the issue when installing packages through 'Composer' on Windows is that the Composer installation directory is NOT set within your %PATH% variable.
This stops the Composer commands from executing in the command-line/terminal until you update your %PATH% variable.
The default installation for global packages is: '%APPDATA%\Composer\vendor\bin'.
Your 'PATH' will need to be appended to this directory with your User directory attached also. ( Which is fairly simply to do but doesn't fix the issue completely )
The 'Absolute' path you will need to use (Windows) is:
'C:\Users\USERNAME\AppData\Roaming\Composer\vendor\bin.'
(Replace USERNAME with your account username)
Adding The Absolute Path:
To append your User to the default path on:
Windows 7:
' Go to:
- Control Panel > Users > 'Select your User' > *Click 'Change my environment variables'
Windows 8/10:
' Go to:
- Start > Search > ' Edit Environment Variables ... ' * Click the first option. (You will need to be admin)
Once the 'Environment Variable' box appears, in the top table you should see a 'PATH' Variable. If your PATH contains a 'Value' already, this is fine! You will need to copy/keep the value in place! Deleting it or changing it may cause you major system errors
(As you can see from my image, the composer directory is already in place)
Click the 'PATH' variable and press 'Edit'. Copy (DONT DELETE) any values in the box, once copied append a semi-colon ; to the end of the value.
(If you don't already have a PATH variable simply press 'New', enter PATH in the variable box and continue with this guide. You will not need to add the semi-colon if you are adding a New PATH )
After the semi-colon (or for the newly created ones, in the empty value box) enter the ^ 'Absolute Path' with your Username in place as show above, once done press 'Ok'.
Absolute Path: 'C:\Users\YOURUSERNAME\AppData\Roaming\Composer\vendor\bin.'
To be sure you have done this successfully and to check if your PATH has changed you will need to restart any applications that may have been using the PATH directory.
To test, simply open your terminal (CMD) and type:
' echo %PATH% '
This will output various lines of directories, the last line printed in the terminal should be your recently added PATH directory ^.
/ Installation Failed :
After appending the user and placing Composers System-wide vendor bin in your $PATH, this may work for you and some may be able to continue with installing/using Laravel. For others especially on Windows you may encounter terminal errors such as:
- ' Installation failed, reverting ./composer.json to its original content' or
- 'Installation request for Symfony/Console (Locked at v3.x) ' etc (Symfony could be a different package name for you)
This can be various reasons, most commonly due the out of date/incompatible dependencies loaded in from your ' ./composer/composer.json ' file.
Solution:
The 'composer global require' command may cause allot of dependency conflicts. To avoid this you can use safer alternative to 'composer global require' - 'Cgr' Created by: Greg Anderson (GitHub) (Click HERE)
As explained on the GitHub page, the 'Cgr' script behaves similarly to 'composer global require' using 'composer require' tp install a 'global-per-user' copy of a command-line tool but also in an isolated location that will not cause dependency conflicts with other installed global tools/packages.
The 'Cgr' script provides a replacement for installing Php command line tool/packages globally.
The 'Cgr' script will create a separate directory for each project you use it for, by default the installation directory location is:
' /.composer/global/org/Project '
Any binary scripts listed in the installed projects 'composer.json' file will be installed to the standard composer bin directory:
' /.composer/vendor/bin '
/ Installation & Use:
As explained on the GitHub page again, 'Cgr' has no dependencies of its own, so it is safe to install via the original Composer global require command:
' composer global require consolidation/cgr '
(Assuming you have already set your Vendor/vin from the 'Composer Home Directory' to your $PATH - As shown above ^ )
Once installed, you may now substitute in 'cgr' for any command line tool that has an installation instructing to use composer 'global require; command.
Examples & Fix:
If you have issues displayed such as 'symfony/console' etc you can use the cgr command to install the required dependencies for that package.
- ' cgr symfony/installer ' instead of:
- ' composer global require symfony/installer'
To fix the version issue run:
- ' cgr symfony/process:3.4 ' ( Replacing 3.4 with the version you require)
If you had no dependency issues, and you simply could not install Laravel after placing Composers vendor bin directory your $PATH you should now be able to do so succesffully using the 'cgr' command rather than the 'composer global require' command.
Install Laravel:
- ' cgr laravel/installer ' instead of:
- ' composer global require laravel/installer '
Once installed you can now continue with the Laravel guide to further create/develop your Laravel site. Enter the directory you wish to create a Laravel project and run the command:
- ' laravel new project ' (Replacing project with your project name)
DONE XD
You should now be able to build/run Laravel projects freely without encountering those errors. You can also now use cgr for installing any other packages you require.
Thank you for reading! This guide was built to firstly remind myself of the headache involved switching from developing Laravel sites on a Mac machine to now using Windows. I hope this has helped you!
Jordan 'JHecz' Crook. (byCrook.co.uk)
@JHeczG
Top comments (4)
Nice article here.
You can resume the work by using which has all-in-one package (including Composer)
Laragon
Thank you :) & Yes! Great suggestion, thank you also.
Still on Windows 7? 👻
On this machine, yeah unfortunately lol