Community

Join 4,000+ others and never miss out on new tips, tutorials, and more.

Github Twitter Newsletter Slack Discord Support

Version

Theme

How to Install Open Swoole

Latest version: pecl install openswoole-25.2.0 | composer require openswoole/core:22.1.5

Important: Please make sure you have followed the prerequisites guide before trying to install Open Swoole, this ensures you have an up-to-date system and all the required third-party packages and libraries.

Docker

Installing via Open Swoole Docker

docker pull openswoole/swoole

Linux Systems

Installing via Open Swoole Ubuntu PPA

You can install Open Swoole binary releases via the Official Open Swoole Ubuntu PPA. For example, on Ubuntu or Debian:

Install Open Swoole on Ubuntu 20.04 LTS (Focal Fossa)

apt update
apt install -y software-properties-common && add-apt-repository ppa:ondrej/php -y
apt install -y software-properties-common && add-apt-repository ppa:openswoole/ppa -y
# choose one PHP version:
#apt install -y php7.4-openswoole
#apt install -y php8.0-openswoole
apt install -y php8.1-openswoole

Install Open Swoole on Ubuntu 22.04 LTS (Jammy Jellyfish)

apt update
apt install -y software-properties-common && add-apt-repository ppa:openswoole/ppa -y
# choose one PHP version:
#apt install -y php7.4-openswoole
#apt install -y php8.0-openswoole
apt install -y php8.1-openswoole

Install Open Swoole on CentOS

You can install Open Swoole binary releases via the Remi's RPM repository.

Install Remin Rpo on RHEL CentOS, Fedora

Install Epel and Remi Repo in RHEL:

# On RHEL/CentOS 8
yum install http://rpms.remirepo.net/enterprise/remi-release-8.rpm
yum update
yum --enablerepo=remi install package

#On RHEL/CentOS 7
yum install http://rpms.remirepo.net/enterprise/remi-release-7.rpm
yum update
yum --enablerepo=remi install package

Install Remi Repo in Fedora:

dnf install http://rpms.remirepo.net/fedora/remi-release-35.rpm   #[On Fedora 34]
dnf install http://rpms.remirepo.net/fedora/remi-release-34.rpm   #[On Fedora 34]
dnf install http://rpms.remirepo.net/fedora/remi-release-33.rpm   #[On Fedora 33]
dnf install http://rpms.remirepo.net/fedora/remi-release-32.rpm   #[On Fedora 32]
yum --enablerepo=remi install package

Install Open Swoole on RHEL CentOS, Fedora

# choose one PHP version:
#yum install php74-php-openswoole
#yum install php80-php-openswoole
yum install php81-php-openswoole

Installing via PHP PECL

Open Swoole is released as a PECL package and can be installed using the command line from the binaries. This is the easiest and quickest way to get working with Open Swoole.

#!/bin/bash

# Make sure PECL is available...
$ sudo apt install php-dev

# Latest release of Open Swoole via PECL
$ sudo pecl install openswoole

Or to install a specific version using PECL:

#!/bin/bash
$ sudo pecl install openswoole-22.0.0

Windows

Install Open Swoole on Windows

It is recommend to use Ubuntu on WSL to use Open Swoole on Windows.

You must be running Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11.

wsl --install

Install Open Swoole on WSL / WSL2 (Ubuntu)

apt update
apt install -y software-properties-common && add-apt-repository ppa:ondrej/php -y
apt install -y software-properties-common && add-apt-repository ppa:openswoole/ppa -y
# choose one PHP version:
#apt install -y php7.4-openswoole
#apt install -y php8.0-openswoole
apt install -y php8.1-openswoole

PECL Configuration Options for Open Swoole

When installing Open Swoole via PECL, during the installation it will ask you if you would like to enable certain features, this can be provided before running the installation, this helps with automating the installation of Swoole or for when you don't want the installation to stop and wait for input. Some options require third party libraries to be installed, see prerequisites.

Shorthand Configure Flag

#!/bin/bash
$ pecl install -D 'enable-sockets="no" enable-openssl="yes" enable-http2="yes" enable-mysqlnd="yes" enable-hook-curl="yes" enable-cares="yes" with-postgres="yes"' openswoole

Longhand Configure Flag

#!/bin/bash
$ pecl install --configureoptions 'enable-sockets="no" enable-openssl="yes" enable-http2="yes" enable-mysqlnd="yes" enable-hook-curl="yes" enable-cares="yes" with-postgres="yes"' openswoole

Note The Open Swoole PECL releases is later than the GitHub releases

MacOS Systems

Install Open Swoole with Brew and PECL

#!/bin/bash

# If you haven't got PHP installed
$ brew install php

$ pecl install openswoole

Install Open Swoole with MacPorts

sudo port install php-openswoole

Building Open Swoole from source

Make sure to read the prerequisites first before compiling Swoole.

To compile and install the Swoole extension for PHP, we can clone the repository from GitHub where Swoole is developed, checkout the version you want to compile and manually install it.

Download the source package from GitHub Releases or clone from the git repository.

#!/bin/bash

# Install git to access the source code from GitHub
$ sudo apt install git

$ cd /tmp && git clone https://github.com/openswoole/ext-openswoole.git && \
    cd ext-openswoole && \
    git checkout v22.0.0 && \
    phpize  && \
    ./configure --enable-openssl \
                --enable-mysqlnd \
                --enable-sockets \
                --enable-http2 \
                --enable-hook-curl \
                --with-postgres \
                --enable-cares && \
    sudo make && sudo make install

The script above will clone Open Swoole from GitHub, checkout v4.6.7 and setup Open Swoole ready to compile using phpize. We then use ./configure to build Open Swoole with the options we want to enable, everything is then compiled using make and make install. You can choose which configuration options you need, see the configuration parameters for more information.

You may need to run make install with sudo privileges.

Enable Open Swoole extension in PHP

After installing the Swoole extension to the PHP extensions directory, you will need to enable Open Swoole so that PHP can load the extension when executing code.

Manually enabling Open Swoole via php.ini

On most systems Open Swoole can be enabled by directly editing your php.ini configuration file, you will want to add extension=openswoole to the end of the file and then Open Swoole should be enabled.

#!/bin/bash

# Check the loaded CLI php.ini config file location
$ php -i | grep php.ini

# Add the openswoole.so extension to the end of your loaded cli php.ini
$ sudo bash -c "echo 'extension=openswoole' >> $(php -i | grep /.+/php.ini -oE)"

# Manually set the path of your php.ini file
$ sudo bash -c 'echo "extension=openswoole" >> /etc/php/7.4/cli/php.ini'

# Check if the Swoole extension has been enabled
$ php -m | grep openswoole

Enabling Open Swoole via phpenmod

Some Linux distributions like Debian or Ubuntu use the PHP mods-available to load PHP extensions, in this case you can use phpenmod to enable Swoole. Follow the commands below to get Swoole enabled.

Make sure to change <PHP_VERSION> to the version of PHP that you have installed.

#!/bin/bash

# Create a Swoole extension PHP ini file, letting PHP know which modules to load
$ sudo bash -c "cat > /etc/php/<PHP_VERSION>/mods-available/openswoole.ini << EOF
; Configuration for Open Swoole
; priority=30
extension=openswoole
EOF"

# Enable the Open Swoole extension only on CLI mode
$ sudo phpenmod -s cli openswoole

# Optional: Enable Open Swoole for specific version of PHP CLI
$ sudo phpenmod -s cli -v 7.4 openswoole

# Check if the Open Swoole extension has been enabled
$ php -m | grep openswoole

You can also disable Open Swoole using phpdismod if you need to (this is not uninstalling, just turning Swoole off):

#!/bin/bash

# Turn off Open Swoole for CLI or a specific PHP install
sudo phpdismod -s cli openswoole
sudo phpdismod -s cli -v 7.4 openswoole

Configuration Parameters

These configuration options are used for enabling some features with Open Swoole, you can use these when installing via PECL or compiling from source.

General Parameters

--enable-openssl

Enable OpenSSL support. It depends on the libssl.so library given by your operating system.

--with-openssl-dir

Set the path of OpenSSL library you want to use, for example:--with-openssl-dir=/opt/openssl/.

--enable-http2

Enable the support of HTTP2. It depends on nghttp2 library which is built into Open Swoole for you. However, you have to enable this option still if you want HTTP2 support.

--enable-hook-curl

Enable native CURL hook support for OpenSwoole coroutines. Since v4.6.0 there is native support for CURL, you must have libcurl4-openssl-dev installed.

--with-postgres

Enable Postgres Coroutine support.

--enable-cares

Enable support for asynchronous DNS support, made possible by compiling the DNS library C-ares. By default this feature is off, if C-ares is not enabled, async DNS queries within OpenSwoole are simulated with a pool of blocking processes to process.

Once C-ares is enabled in OpenSwoole, all the DNS queries produced by the OpenSwoole DNS API System::dnsLookup, System::gethostbyname or OpenSwoole coroutine clients are asynchronous, including the MySQL client, Redis Client, HTTP Client, CURL etc. Also any DNS name resolves as well.

You have to install libc-ares before enabling this flag:

## Centos
yum install -y libc-ares-devel
## Debian & Ubuntu
apt-get install -y libc-ares-dev

Additional Parameters

--enable-mysqlnd

Enable support for mysqlnd, for example this adds support for $mysql->escape(...). You must also install the PHP mysqlnd module for this option to work. However, it is more recommended to use PHP PDO MySQL instead.

--with-postgres

Or use --with-postgres[=DIR] when you have postgres library installed at a custom location.

Enable support for postgres, this adds support for Coroutine PostgreSQL Client

--enable-sockets

Enable sockets support. It depends on the PHP sockets extension. If this configuration has been enabled, the function Swoole\Event::add() can add the connection created by the sockets extension to the event loop of Swoole. And the function getSocket() depends on this configuration being enabled. However, the Coroutine\Socket service can do most things and may be more recommended.

Debug Parameters

--enable-debug

Turn on debugging mode for Swoole. You will need gdb installed to use this parameter.

--enable-debug-log

Enable the debug logs of OpenSwoole. Don't enable this configuration in a production environment.

--enable-trace-log

Turn on the trace log. After enabling this option, OpenSwoole will printout various details of the debug log, which is only used during kernel development.

PHP Compilation Parameters

--enable-openswoole

Statically compile OpenSwoole and extend it to PHP. This option is only used when compiling PHP instead of OpenSwoole.

Upgrading Open Swoole

When a new OpenSwoole version is released, you can upgrade but it depends on how you installed OpenSwoole.

There is no need to uninstall OpenSwoole or delete any previous files, upgrading will overwrite any files or binaries, the install/upgrade process only produces one openswoole.so binary for PHP to use.

For changelogs and updates, check out posts at https://openswoole.com/article/

Upgrading using PECL

If you installed via PECL, you can just run:

#!/bin/bash
$ sudo pecl upgrade openswoole

Or to install a specific version using PECL:

#!/bin/bash
$ sudo pecl upgrade openswoole-22.0.0

Upgrading from source

If you compiled OpenSwoole yourself from GitHub, you can recompile and install new changes/version again.

#!/bin/bash

# Enter the directory where you cloned OpenSwoole
cd ext-openswoole

# Pull down any new changes or checkout a new tag
git pull | git checkout v22.0.0 | git checkout master

# Reconfigure the build for PHP again
phpize clean && phpize

# Configure OpenSwoole features again
./configure --enable-openssl \
            --enable-mysqlnd \
            --enable-sockets \
            --enable-http2 \
            --enable-hook-curl

...

# Perform a clean so we can recompile
make clean

# Build and Compile new version
sudo make && sudo make install

Upgrading from Open Swoole Ubuntu PPA on Ubuntu OR Windows WSL

If you installed OpenSwoole via the Open Swoole Ubuntu PPA, you should receive updates via your package manager. For example, on Ubuntu or Debian:

#!/bin/bash

sudo apt update
sudo apt upgrade

# Upgrade Open Swoole package only, change to what you have installed
sudo apt update
sudo apt install --only-upgrade php8.1-openswoole

If you are using a new version of PHP, perform a apt search openswoole to install the correct version.

#!/bin/bash

# Show Swoole installed options and information
$ php --ri openswoole

...

# Example output from command above...
openswoole

Open Swoole => enabled
Author => Open Swoole Group <hello@openswoole.com>
Version => 22.0.0
Built => Sep 20 2022 08:37:15
coroutine => enabled with boost asm context
kqueue => enabled
rwlock => enabled
sockets => enabled
openssl => OpenSSL 3.0.5 5 Jul 2022
dtls => enabled
http2 => enabled
json => enabled
curl-native => enabled
pcre => enabled
c-ares => 1.18.1
zlib => 1.2.11
brotli => E16777225/D16777225
mysqlnd => enabled
postgresql => enabled

Directive => Local Value => Master Value
openswoole.enable_coroutine => On => On
openswoole.enable_preemptive_scheduler => Off => Off
openswoole.display_errors => On => On
openswoole.unixsock_buffer_size => 262144 => 262144

Install OpenSwoole Core

You have to install OpenSwoole Core composer library to access to a few features such as Psr support and addon functions implemented with PHP:

#!/bin/bash

composer require openswoole/core

Last updated on February 7, 2023

⭐ at Github Follow Twitter Subscribe Newsletter Join Slack Join Discord