---
title: "Installation"
version: "main"
source: "Installation/Index.rst"
rendered: "2026-09-24T07:51:28+00:00"
---

# Installation {#installation}

There are several ways to install Surf:

1.  [Download phar archive](#installation-download-phar)
1.  [Global composer installation](#installation-global-composer)
1.  [Local composer installation](#installation-local-composer)
1.  [Building a Surf phar from source](#installation-build-phar)

## Download phar archive {#installation-download-phar}

To install Surf as phar archive, run the following commands:

```php
mkdir /usr/local/surf
curl -L https://github.com/TYPO3/Surf/releases/download/3.6.2/surf.phar -o /usr/local/surf/surf.phar
chmod +x /usr/local/surf/surf.phar
ln -s /usr/local/surf/surf.phar /usr/local/bin/surf

```

You may need extended privileges e.g. `sudo`.

This way, you can add `/usr/local/surf` to `PHP Include Paths` in your IDE.

### Upgrading Surf {#upgrading-surf}

Later, to upgrade Surf, run the command:

```php
surf self-update

```

## Global composer installation {#installation-global-composer}

To install Surf globally via composer, run the following command:

```php
composer global require typo3/surf:^3.6

```

This way, you can add `~/.composer/vendor/typo3/surf` to `PHP Include Paths` in your IDE.

## Local composer installation {#installation-local-composer}

To install Surf within your project via composer, run the following command:

```php
composer require typo3/surf:^3.6

```

The advantage of this method is that you can directly inspect the source files of surf without any further configuration in your IDE.

> [!NOTE]
> Because of surf's dependencies it could be that you can't install surf in your project root. In that case you should install surf in a sub directory.

## Building a Surf phar from source {#installation-build-phar}

Surf is built using [humbug/box](https://github.com/humbug/box/) and the process is simple:

-   Install humbug/box as described in its documentation
-   Clone or download the desired branch of typo3/surf
-   `cd your/surf/folder`
-   `composer install --no-dev`
-   `path/to/box compile`

The generated `surf.phar` in the folder `release` should work as expected.