Simple Setup (Linux/Mac OS)

On Mac OS X and Linux, using the embedded web server is the most convenient and easy option.

1. Install PHP and MariaDB

For Mac OS, we suggest installing PHP through homebrew, so you need to install it first.

Afterwards, run the following command to install PHP and MariaDB:

brew install php mariadb@10.3

Furthermore, we recommend to install Sequel Ace, which is an open source database management tool for OSX - this helps to get a glance into the database.

On Linux, installing PHP and MariaDB is different depending on which distribution you have.

Install php

The following steps were written for php 7.4 but will work for php 8.0 too and presumably for any further version. (Just make sure you 'fully' qualify your major php version to 2 digits and dot: '8.0').

The latest php version of the Debian repository is, at the time of writing, only php 7.3. If you want to continue with php 7.3 you can skip the step below and use 7.3 instead of 7.4 in the further code. If you want to check if a certain php version is available on your system, use:

apt search php7.4
Add repository (for latest php version)

To be able to get a more recent php version, we need to use a third party repository. In this case, we will be using DEB.SURY.ORG.

# Update your system
sudo apt update && sudo apt upgrade

# Transfer data safely (SSL) and more
sudo apt -y install apt-transport-https lsb-release ca-certificates wget

# Add GPG key
sudo wget -O /etc/apt/trusted.gpg.d/php.gpg

# Add the DEB.SURY.ORG repository
echo "deb $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list
Install php 7.4

install the most common/required php extensions for the use with Neos:

sudo apt install php7.4 php7.4-{common,mbstring,mysql,xml,imagick,curl,intl,igbinary}

Install mariadb/mysql

MySQL was replaced with MariaDB in the Debian repository - so we will be using MariaDB. (Make sure if you are using an older Debian version, that your MariaDB version fullfills the System Requirements)

sudo apt install mariadb-server

sudo service mysql start

# Answer all with (Y)es
sudo mysql_secure_installation

# Enter the MySQL Shell (ctrl+c to exit)
sudo mysql

Create a database user (MariaDB/MySQL)

You should create a new user instead of using the root user. See [SOLVED] An exception occurred in driver: SQLSTATE[HY000] [1698] Access denied for user 'root'@'localhost'

# Enter the MySQL Shell (ctrl+c to exit)
sudo mysql
CREATE USER 'neos'@localhost;

-- Let user have access to all databases and set user password
GRANT ALL PRIVILEGES ON *.* TO 'neos'@localhost IDENTIFIED BY '123456';

-- Apply changes
# Test the user
mysql -u neos -p
# -p will ask you to type in the password

I have a user what now?

Further tasks like creating the database can be handled later with comfort via the Setup Tool but you can also go ahead and create a Database now:

# The manual way - or wait for the GUI
CREATE DATABASE MyNeosDatabase CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci

Just remember the username and password (for the GUI Setup) and head to the next step.

2. Install composer

Composer is the PHP dependency manager, similar to NPM for Node.js, or Maven for Java. If you do not have it installed yet, you need to install it now because it is the way to install Neos then.

curl -sS | php

By issuing this command, Composer will get downloaded as composer.phar to your working directory. We suggest to have composer installed globally, so you can simply move it to a directory within your $PATH environment:

mv composer.phar /usr/local/bin/composer

You may check your composer's version by typing “composer -V” ...

composer self-update

3. Check out the project 
(or start from scratch)

Now, this part is different depending on whether you want to start from scratch, or you have an existing project you want to work on.

Start from Scratch:

To create a new project, use the following commands, which will create the base directory structure and download all dependencies.

# with native Composer:
composer create-project neos/neos-base-distribution neos-example

# ALTERNATIVE, with Composer through Docker:
docker run -v %cd%:/app -it --rm composer create-project neos/neos-base-distribution neos-example

We furthermore strongly recommend to directly create a new Git repository for making the installation reproducible:

cd neos-example
git init
git add .
git commit -m "TASK: Initial Commit"
# optionally, also run "git remote add ..." and "git push"

Start with a good boilerplate:

The Neos-Skeleton provides an easy and powerful start for new projects - beginner-friendly and highly scalable. It is frontend tooling agnostic.

On top, it adds well-tested community packages to provide everything you need for an amazing website.


  • A powerful best practice layout rendering mechanism
  • Best practice folder and naming structure
  • A well-rounded set of packages to build typical websites

-> Steps to get started


Check out an existing project:

To check out an existing project, simply clone it and run composer install to install all dependencies.

git clone http://YOUR-PROJECT-URL-HERE your-project
cd your-project

# with native Composer:
composer install

# ALTERNATIVE, with Composer through Docker:
docker run -v %cd%:/app -it --rm composer install

4. Start "embedded server"

In your project directory, run the following command to start the embedded development web server:

./flow server:run

# After a while, the following is shown:
# Server running. 
# Please go to to browse the application.

Speed at first launch

When executing ./flow server:run for the first time, it takes between 10 and 30 seconds until the server is fully started. This is because all classes are analyzed and precompiled on the initial start. On subsequent invocations, the server starts up in less than a second.

5. Visit the setup

Now, go to the "Php embedded development server"

... and you are redirected to the Neos "Setup Tool".