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 / MySQL

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. We don't yet have distribution-specific guides here yet.

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".