How to Install Laravel Locally on Windows, macOS, and Linux

Introduction

Installing Laravel is usually straightforward, but beginners often get stuck because several tools work together: PHP, Composer, the Laravel installer, Node, a database, and a local development server.

This guide walks through the practical setup process for Windows, macOS, and Linux. The goal is not just to run one command successfully. The goal is to understand what Laravel needs, how to confirm your environment is working, and how to avoid the common setup issues that slow developers down before they write any application code.

What You Need Before Installing Laravel

A modern Laravel project needs a working PHP environment, Composer for PHP dependencies, and Node with NPM or Bun if the application uses frontend assets. Most real projects also need a database such as SQLite, MySQL, PostgreSQL, or another supported database driver.

Before creating a Laravel app, check that your terminal can find PHP and Composer.

php -v
composer --version

If either command fails, Laravel itself is not the problem yet. Fix the PHP or Composer installation first.

Recommended Installation Paths

There are two sensible ways to install Laravel locally.

Option 1: Laravel Installer

The Laravel installer is convenient when you create Laravel projects regularly.

composer global require laravel/installer
laravel new example-app

Option 2: Composer Create Project

If you do not want to install a global Laravel command, Composer can create the project directly.

composer create-project laravel/laravel example-app

Both approaches can produce a working Laravel application. The Laravel installer may offer guided choices during setup, while Composer is a simple and reliable baseline.

Installing Laravel on Windows

On Windows, choose one local development setup and keep it consistent. Good options include Laravel Herd, Laragon, Docker-based workflows, or a manually configured PHP and Composer setup.

If PHP and Composer are already installed and available in PowerShell, you can install Laravel like this:

composer global require laravel/installer
laravel new example-app
cd example-app

If the laravel command is not recognized after installation, the most common cause is that Composer’s global vendor bin directory is not on your system PATH. Restart the terminal first. If it still fails, check Composer’s global bin path.

composer global config bin-dir --absolute

You can also skip the global installer and use Composer directly:

composer create-project laravel/laravel example-app
cd example-app

Installing Laravel on macOS

On macOS, many Laravel developers use Laravel Herd because it provides a native PHP development environment with minimal setup. You can also use Homebrew, Docker, or a manual PHP and Composer setup.

With PHP and Composer available, the commands are the same:

composer global require laravel/installer
laravel new example-app
cd example-app

If you prefer Composer only:

composer create-project laravel/laravel example-app
cd example-app

If you use Herd, Laravel applications inside a parked directory can be served through local .test domains. That is useful when you want a more realistic local domain than localhost:8000.

Installing Laravel on Linux

On Linux, install PHP, Composer, and any PHP extensions required by your Laravel version and database driver. The exact package names depend on your distribution.

After PHP and Composer are available, create the Laravel app:

composer create-project laravel/laravel example-app
cd example-app

Or use the Laravel installer:

composer global require laravel/installer
laravel new example-app
cd example-app

On Linux servers, be careful not to confuse local development setup with production deployment. A production web server should point to Laravel’s public directory, not the project root.

Starting the Laravel Development Server

For a basic local setup, Laravel can be served with Artisan.

php artisan serve

The app is usually available at:

http://127.0.0.1:8000

For projects with frontend assets, install dependencies and run the frontend build or development server as needed.

npm install
npm run dev

Some newer Laravel project setups also provide a Composer script that runs the local development stack. Check the generated composer.json file before assuming every project uses the same command.

Configure the Environment File

Laravel stores environment-specific settings in the .env file. This file should not be committed to source control because it may contain secrets and machine-specific values.

Key values to check early:

APP_NAME="Example App"
APP_ENV=local
APP_KEY=base64:...
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000

For local development, APP_DEBUG=true is useful. In production, it should be false.

If your project does not have an application key, generate one:

php artisan key:generate

Set Up the Database

Laravel can use SQLite for a fast local start, or a database server such as MySQL or PostgreSQL when your application needs a closer match to production.

Example MySQL configuration:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=example_app
DB_USERNAME=root
DB_PASSWORD=

After configuring the database, run migrations:

php artisan migrate

If migrations fail, read the first database error carefully. It usually points to a missing database, wrong credentials, unavailable database server, or missing PHP extension.

Verify the Installation

A Laravel installation is healthy when the app loads in the browser, Artisan commands run, and migrations can connect to the database.

php artisan about
php artisan route:list
php artisan migrate:status

If these commands work, you are ready to start building routes, controllers, models, and views.

Common Installation Problems

The laravel Command Is Not Recognized

The Laravel installer is probably installed, but Composer’s global bin directory is not on your PATH. Restart your terminal and check Composer’s global bin directory.

composer global config bin-dir --absolute

Composer Cannot Install Dependencies

This usually means PHP is missing an extension, Composer is using a different PHP version than expected, or the network cannot reach package repositories. Start by checking PHP and Composer versions.

php -v
composer diagnose

The App Key Is Missing

Generate an application key:

php artisan key:generate

Database Connection Failed

Confirm the database server is running, the database exists, the credentials are correct, and the matching PHP database extension is installed.

Permission Errors on Linux

The web server and CLI user need appropriate access to Laravel’s writable directories, especially storage and bootstrap/cache. Avoid broad permissions as a lazy fix; set ownership and permissions deliberately for your environment.

Which Local Development Setup Should You Choose?

Beginners should choose the setup that lets them spend more time learning Laravel and less time maintaining local infrastructure.

• Laravel Herd: Good for macOS and Windows developers who want a polished Laravel-specific local environment.
• Laragon: Good for Windows developers who want a flexible local PHP stack.
• Docker: Good for teams that want reproducible environments, but it can add complexity for beginners.
• Manual PHP and Composer: Good if you want to understand the stack deeply, but it requires more setup discipline.

What to Do After Installing Laravel

Once Laravel runs locally, do not jump straight into a large application. Build a small flow first:

1. Create a route.
2. Return a Blade view.
3. Create a controller.
4. Create a model and migration.
5. Store a record in the database.
6. Display records on a page.

This small loop teaches the Laravel request lifecycle better than reading every feature page at once.

Frequently Asked Questions

Do I need Laravel Herd to install Laravel?

No. Herd is a convenient local development environment, but Laravel can also be installed with Composer, Docker-based tooling, Laragon, or a manually configured PHP setup.

Can I install Laravel without the Laravel installer?

Yes. Use composer create-project laravel/laravel example-app.

Do I need Node to learn Laravel?

You can learn many Laravel backend concepts without focusing on frontend tooling, but modern Laravel projects often use Node, NPM, or Bun for frontend assets.

Should I use SQLite or MySQL locally?

SQLite is convenient for quick starts. MySQL or PostgreSQL may be better when your local environment should closely match production.

Why does Laravel show a blank page or 500 error after installation?

Common causes include a missing app key, bad file permissions, dependency installation failure, invalid environment configuration, or a database connection issue.

Conclusion

Installing Laravel is mostly about getting the surrounding environment right. Laravel needs PHP, Composer, a project directory, a valid environment file, and usually a database. Once those pieces are working, the framework itself gives you a clean path into routing, controllers, Blade templates, migrations, Eloquent, APIs, queues, caching, and deployment.

If you are new to Laravel, keep the first installation simple. Create the app, run it locally, configure the database, run migrations, and build one small feature. That gives you a stable foundation before you move into more advanced Laravel development.

FAQ

Do I need Laravel Herd to install Laravel?

No. Herd is convenient, but Laravel can also be installed with Composer, Docker-based tooling, Laragon, or a manually configured PHP setup.

Can I install Laravel without the Laravel installer?

Yes. Use composer create-project laravel/laravel example-app.

Do I need Node to learn Laravel?

You can learn many Laravel backend concepts without focusing on frontend tooling, but modern Laravel projects often use Node, NPM, or Bun for frontend assets.

Should I use SQLite or MySQL locally?

SQLite is convenient for quick starts. MySQL or PostgreSQL may be better when your local environment should closely match production.

Why does Laravel show a blank page or 500 error after installation?

Common causes include a missing app key, bad file permissions, dependency installation failure, invalid environment configuration, or a database connection issue.

Sources

1. https://laravel.com/docs/installation
2. https://laravel.com/docs/configuration