How to Install Swoole
Important: Please make sure you have followed the prerequisites guide before trying to install Swoole, this ensures you have an up-to-date system and all the required third-party packages and libraries. You should also have PHP installed first, refer to the PHP manual for this; in general though PHP can be installed via:
Either compile PHP directly or use your Unix like package installation system, for example on Ubuntu:
#!/bin/bash
$ sudo apt-get update && sudo apt-get upgrade # Update your server
$ sudo apt-get install php # Install default PHP package
# Check installed version and info
$ php -v
Linux Systems
Installing via PECL binary releases
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 Swoole.
#!/bin/bash
# Make sure PECL is available...
$ sudo apt install php-dev
# Latest relese of Swoole via PECL
$ sudo pecl install swoole
Or to install a specific version using PECL:
#!/bin/bash
$ sudo pecl install swoole-4.5.5
PECL Configuration Options for Swoole
When installing 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-swoole-json="no" enable-swoole-curl="yes"' swoole
Longhand Configure Flag
#!/bin/bash
$ pecl install --configureoptions 'enable-sockets="no" enable-openssl="yes" enable-http2="yes" enable-mysqlnd="yes" enable-swoole-json="no" enable-swoole-curl="yes"' swoole
Note The Swoole PECL releases is later than the GitHub releases
Using Deb.Sury Swoole Packages
You can install Swoole using the prebuilt packages from the ondrej/php PPA, you can follow the main Linux Requirements. But make sure you install PHP first.
If you haven't already, add the ondrej/php PPA first:
#!/bin/bash
# Install the Deb.Sury PHP Ubuntu PPA source
$ sudo apt install software-properties-common
$ sudo add-apt-repository ppa:ondrej/php
$ sudo apt-get update
Then you will want to search to see which Swoole package you want to install based on the version of PHP you have:
#!/bin/bash
$ sudo apt search swoole
...
php7.2-swoole/focal 4.6.7-1+ubuntu20.04.1+deb.sury.org+1 amd64
Swoole Coroutine Fiber Async Programming Framework for PHP
php7.3-swoole/focal 4.6.7-1+ubuntu20.04.1+deb.sury.org+1 amd64
Swoole Coroutine Fiber Async Programming Framework for PHP
php7.4-swoole/focal 4.6.7-1+ubuntu20.04.1+deb.sury.org+1 amd64
Swoole Coroutine Fiber Async Programming Framework for PHP
php8.0-swoole/focal,now 4.6.7-1+ubuntu20.04.1+deb.sury.org+1 amd64
Swoole Coroutine Fiber Async Programming Framework for PHP
Above you can see a list of Swoole compatible packages from ppa:ondrej/php, pick one which matches the version of PHP you have installed.
To install Swoole with PHP 8.0, you can run for example:
#!/bin/bash
# Install Swoole for PHP 8.0
$ sudo apt install php8.0-swoole
# Check that Swoole is loaded
$ php -m | grep swoole
Note: The php-swoole package is the same as php8.0-swoole.
MacOS Systems
#!/bin/bash
# If you haven't got PHP installed
$ brew install php
$ pecl install swoole
Building 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/swoole/swoole-src.git && \
cd swoole-src && \
git checkout v4.6.7 && \
phpize && \
./configure --enable-openssl \
--enable-mysqlnd \
--enable-sockets \
--enable-http2 \
--enable-swoole-curl \
--enable-swoole-json && \
sudo make && sudo make install
The script above will clone Swoole from GitHub, checkout v4.6.7 and setup Swoole ready to compile using phpize. We then use ./configure to build 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 Swoole extension in PHP
After installing the Swoole extension to the PHP extensions directory, you will need to enable Swoole so that PHP can load the extension when executing code.
Manually enabling Swoole via php.ini
On most systems Swoole can be enabled by directly editing your php.ini configuration file, you will want to add extension=swoole to the end of the file and then Swoole should be enabled.
#!/bin/bash
# Check the loaded CLI php.ini config file location
$ php -i | grep php.ini
# Add the swoole.so extension to the end of your loaded cli php.ini
$ sudo bash -c "echo 'extension=swoole' >> $(php -i | grep /.+/php.ini -oE)"
# Manually set the path of your php.ini file
$ sudo bash -c 'echo "extension=swoole" >> /etc/php/7.4/cli/php.ini'
# Check if the Swoole extension has been enabled
$ php -m | grep swoole
Enabling 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/swoole.ini << EOF
; Configuration for Swoole
; priority=25
extension=swoole
EOF"
# Enable the Swoole PHP extension only on CLI mode
$ sudo phpenmod -s cli swoole
# Optional: Enable Swoole for specific version of PHP CLI
$ sudo phpenmod -s cli -v 7.4 swoole
# Check if the Swoole extension has been enabled
$ php -m | grep swoole
You can also disable Swoole using phpdismod if you need to (this is not uninstalling, just turning Swoole off):
#!/bin/bash
# Turn off Swoole for CLI or a specific PHP install
sudo phpdismod -s cli swoole
sudo phpdismod -s cli -v 7.4 swoole
Configuration Parameters
These configuration options are used for enabling some features with 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 Swoole for you. However, you have to enable this option still if you want HTTP2 support.
--enable-swoole-json
Enable Swoole JSON support, this enables the Swoole JSON functions. You must also install PHP-JSON as well.
--enable-swoole-curl
Enable native CURL hook support for Swoole coroutines. Since v4.6.0 there is native support for CURL, you must have libcurl4-openssl-dev installed.
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.
--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 Swoole. Don't enable this configuration in a production environment.
--enable-trace-log
Turn on the trace log. After enabling this option, Swoole will printout various details of the debug log, which is only used during kernel development.
PHP Compilation Parameters
--enable-swoole
Statically compile Swoole and extend it to PHP. This option is only used when compiling PHP instead of Swoole.
Upgrading Swoole
When a new Swoole version is released, you can upgrade but it depends on how you installed Swoole.
There is no need to uninstall Swoole or delete any previous files, upgrading will overwrite any files or binaries, the install/upgrade process only produces one swoole.so binary for PHP to use.
For changelogs and updates, check out:
Upgrading using PECL
If you installed via PECL, you can just run:
#!/bin/bash
$ sudo pecl upgrade swoole
Or to install a specific version using PECL:
#!/bin/bash
$ sudo pecl upgrade swoole-4.5.5
Upgrading from source
If you compiled Swoole yourself from GitHub, you can recompile and install new changes/version again.
#!/bin/bash
# Enter the directory where you cloned Swoole
cd swoole-src
# Pull down any new changes or checkout a new tag
git pull | git checkout v4.6.7 | git checkout master
# Reconfigure the build for PHP again
phpize clean && phpize
# Configure Swoole features again
./configure --enable-openssl \
--enable-mysqlnd \
--enable-sockets \
--enable-http2 \
--enable-swoole-curl
...
# Perform a clean so we can recompile
make clean
# Build and Compile new version
sudo make && sudo make install
Upgrading from Deb.Sury Packages
If you installed Swoole via the ondrej/php PPA, you should receive updates via your package manager. For example, on Ubuntu or Debian:
#!/bin/bash
sudo apt update
sudo apt upgrade
# Upgrade Swoole package only, change to what you have installed
sudo apt update
sudo apt install --only-upgrade php-swoole
If you are using a new version of PHP, perform a apt search swoole to install the correct version.
Common Install Errors
If you are having difficulty installing or upgrading Swoole, first check the prerequisites guide but if that does not help, checkout the common installation errors for more help.
Segment Fault Errors
You can follow the instruction about how to debug segment fault errors with Swoole if you come across any.
How to check current enabled options/ install information
#!/bin/bash
# Show Swoole installed options and information
$ php --ri swoole
...
# Example output from command above...
Swoole => enabled
Author => Swoole Team <[email protected]>
Version => 4.5.5
Built => Jun 23 2021 14:02:14
coroutine => enabled
epoll => enabled
eventfd => enabled
signalfd => enabled
cpu_affinity => enabled
spinlock => enabled
rwlock => enabled
sockets => enabled
openssl => OpenSSL 1.1.1f 31 Mar 2020
http2 => enabled
pcre => enabled
mutex_timedlock => enabled
pthread_barrier => enabled
futex => enabled
mysqlnd => enabled
async_redis => enabled
Directive => Local Value => Master Value
swoole.enable_coroutine => On => On
swoole.enable_library => On => On
swoole.enable_preemptive_scheduler => Off => Off
swoole.display_errors => On => On
swoole.use_shortname => On => On
swoole.unixsock_buffer_size => 8388608 => 8388608
