Installation Instructions

0. Introduction
1. Install Composer
2. Create a New Craft Project
3. Set up the Database
4. Set up the Web Server
5. Run the installer!

0. Introduction

Craft 3 is available as a Composer package. If you’re unfamiliar with Composer, it’s a package manager (like npm) that attempts to make installing and updating PHP libraries easy via terminal commands.

{tip} If you’d prefer to download a zip file instead, you can download Craft 3 from the Download button in the header of craftcms.com. If you go that route, you can skip to step 3.

Craft’s Composer support has two parts:

craftcms/cms – This is the Composer package that contains all of Craft’s source code.
craftcms/craft – This is a Composer “project” that can be used as a starting point for new Craft projects.

1. Install Composer

You should be running Composer 1.3.0 or later. You can find out your installed version of Composer (if any) by opening your terminal running the following command:

composer -V

If that outputs an error saying composer is not found or not recognized, then Composer isn’t installed. Follow Composer’s instructions to install it:

macOS/Linux/Unix instructions (install it globally)
Windows instructions

If it outputs a version number, but it’s less than 1.3.0, run the following command to update it:

composer self-update

2. Create a New Craft Project

To create a new Craft project, run this command (substituting <PATH> with the path where Composer should create the project):

composer create-project craftcms/craft <PATH>

Note: If Composer complains that your system doesn’t have PHP 7 installed, but you know it’s not an issue because Craft will run with a different PHP install (e.g. through MAMP or Vagrant), use the --ignore-platform-reqs flag.

Composer will take a few minutes to install everything.

Once it’s finished, your project directory should have a file structure like this:

config/...
storage/
templates/
vendor/...
web/...
.env
.env.example
composer.json
craft
craft.bat
LICENSE.md
README.md

See Directory Structure for information on these directories and files.

3. Setting Up the Database

Next up, you need to create a database for your Craft project. Craft 3 supports both MySQL 5.5+ and PostgreSQL 9.5+.

If you’re given a choice, we recommend the following database settings in most cases:

MySQL
- Default Character Set: utf8
- Default Collation: utf8_unicode_ci
PostgreSQL
- Character Set: UTF8

Once you create the database, you’ll need to configure your .env file with the database connection settings. You can either edit the file manually, or run the ./craft setup command from the root project directory in your terminal.

Note: PHP dotenv, which the craftcms/craft project comes with pre-installed, processes the .env file. The advantage of using PHP dotenv is that it offers a place to store sensitive information (like database connection settings) in a file that doesn’t get committed to your Git repository.

4. Set up the Web Server

Create a new web server to host your Craft project. Its document root should point to your public HTML folder. If you’re using Craft’s Composer starter project, then it is the web/ directory by default, but it can be renamed to anything you want as long as your web server is configured to point to it.

If your web host already has a public HTML folder setup to for you that you cannot rename, then you can just copy the contents of Craft’s web folder to it and use your host’s default public HTML folder.

If you’re not using MAMP or another localhosting tool, you will probably need to update your hosts file, so your computer knows to route requests to your chosen host name to the local computer.

macOS/Linux/Unix: /etc/hosts
Windows: \Windows\System32\drivers\etc\hosts

5. Run the installer!

You can test whether you set everything up correctly by pointing your web browser to http://HOSTNAME/index.php?p=admin (substituting HOSTNAME with your new web server’s host name).

Tip: Want to install Craft from the command line? Check out the Craft setup command.

If successful, you will get the Craft installation wizard. The wizard will take you through a couple setup screens, and then perform the installation of Craft.

Not working? Here are a couple tips:

If you’re getting a 404, your server might not be configured to redirect would-be 404’s to index.php correctly. Try going to http://example.com/index.php/admin or http://example.com/index.php?p=admin instead.
If you’re getting other errors then you should revisit the prior steps to ensure everything is set up properly.

The first step of the installer is to accept the license agreement. Scroll down through the agreement (reading it all, of course) and tap or click "Got it" to accept.

The second step is to enter your database connection information. Input the information you saved in Step 3.

The third step of the installer is to create a user account. Don’t be one of those people and be sure to pick a strong password.

The final step is to define your System Name, Base URL, and Language. Craft pre-fills all three based on other settings but you can edit each field before clicking "Finish up".

Now Craft will run the installer and complete the setup process. A few seconds later, you should have a working Craft install!

If it was successful, Craft will redirect your browser to the Control Panel dashboard.

Congratulations, you’ve just installed Craft!

Now get back to work.

Setup from the Command Line

In lieu of using the web browser to run the Craft installer, you can set up Craft from the command line.

After successfully creating a new project via Composer, you'll see a link to the Craft setup command.

$ ./craft setup

This command will run you through a similar wizard as in the web browser but all from the command line. Once you've completed the setup process you can right to the control panel to log in.