Common Installation Errors

Swoole appears in phpinfo() but not in php -m list

Firstly, Swoole is designed to run in PHP CLI mode only. It is not available when run using PHP-FPM or Apache-Mod.

Please make sure you understand the programming model of Swoole first before continuing to install. Checkout the introduction documentation to learn more.

Swoole uses a stateful asynchronous programming model, everything is kept in memory, so traditional PHP programming is usually not allowed in Swoole, especially the use of global variables.

If you find that Swoole is installed via phpinfo() but does not appear in the php -m list, make sure you have enabled Swoole in the correct php.ini file. Sometimes when installing PHP you have your PHP-FPM php.ini file and the standalone PHP CLI php.ini, only make sure you are using the CLI version of PHP.

Check the direct location of your PHP CLI INI file with: php -i | grep php.ini. Refer back to the installation documentation on how to then enable Swoole properly with PHP.


pcre.h: No such file or directory

When compiling Swoole you get the above error.

You must install the pcre and libpcre library.


# Ubuntu/ Debian
$ sudo apt-get install libpcre3 libpcre3-dev

# CentOS/ RedHat
$ sudo yum install pcre-devel


PCRE2 errors: pcre2.h file not found on MacOS Big Sur

You can find the pcre2 location with:

$ pcre2-config --prefix

# For example
/usr/local/Cellar/pcre2/10.36/

Then include the pcre2 library in your path:

sudo ln -s /usr/local/Cellar/pcre2/10.36/include/pcre2.h /usr/local/include/


builtin_saddl_overflow was not declared in this scope

On CentOS only, you get the following error:

error: '__builtin_saddl_overflow' was not declared in this scope
 if (UNEXPECTED(__builtin_saddl_overflow(Z_LVAL_P(op1), 1, &lresult))) {

note: in definition of macro 'UNEXPECTED'
# define UNEXPECTED(condition) __builtin_expect(!!(condition), 0)

This is a known issue. The problem is that the default GCC compiler on CentOS lacks the necessary definitions. Even after upgrading GCC, PECL will still find the old compiler.

To install the driver, you must first upgrade GCC by installing the devtoolset collection, as follows:

sudo yum install centos-release-scl
sudo yum install devtoolset-7
scl enable devtoolset-7 bash


OpenSSL errors: fatal error: openssl/ssl.h file not found

You have to include OpenSSL library in your path:

export LDFLAGS="-L/usr/local/opt/openssl/lib"
export CPPFLAGS="-I/usr/local/opt/openssl/include"

You have to install libopenssl-dev if you have set or enabled: --enable-openssl.

sudo apt install openssl
sudo apt install libssl-dev


OpenSSL is installed in a different location

Determine your OpenSSL directory path:

openssl version -d

You will see the OpenSSL directory like this:

OPENSSLDIR: "/usr/local/etc/[email protected]"

Then you can pass OpenSSL directory when installing Swoole:

--with-openssl-dir=/usr/local/etc/[email protected]

When using PECL to install Swoole, if you want to enable OpenSSL, you can also add the --with-openssl-dir parameter, such as:

enable openssl support? [no] : yes --with-openssl-dir=/opt/openssl/


make or make install cannot be executed or compilation error

When compiling Swoole if you come across the following error:

NOTICE: PHP message: PHP Warning: PHP Startup: swoole: Unable to initialize module
Module compiled with module API=20090626
PHP compiled with module API=20121212
These options need to match
in Unknown on line 0

The version of PHP you have installed is not located within the expected directory or cannot be found by Swoole properly. You must use an absolute path instead.

# Execute phpize
/usr/local/php-5.4.17/bin/phpize

# Configure Swoole to be installed with certain options...
./configure --with-php-config=/usr/local/php-5.4.17/bin/php-config

...

# Execute a Swoole server script...
/usr/local/php-5.4.17/bin/php server.php


Trying to use Xdebug and Swoole

If you are trying to install Xdebug with PHP, Xdebug does not have support with Swoole, because of the programming model used by Swoole and Swoole coroutines are not supported by Xdebug. Instead you should checkout Swoole YASD.


configure: error: C preprocessor /lib/cpp fails sanity check

If you receive the following error:

configure: error: C preprocessor "/lib/cpp" fails sanity check

This indicates the lack of necessary dependent libraries, you can use the following command to install them for CentOS/RedHat:

yum install glibc-headers
yum install gcc-c++


PHP7.4.11 compile new version of Swoole, error asm goto is reported MacOS

When using PHP7.4.11 and trying to compile a new version of Swoole with MacOS, the following error can be encountered:

/usr/local/Cellar/php/7.4.12/include/php/Zend/zend_operators.h:523:10: error: 'asm goto' constructs are not supported yet
        __asm__ goto(
                ^

4 errors generated.
make: *** [ext-src/php_swoole.lo] Error 1
ERROR: `make' failed

The solution to this problem on MacOS is to modify /usr/local/Cellar/php/7.4.12/include/php/Zend/zend_operators.h. Modify the header file path to look like the following:

#if defined(HAVE_ASM_GOTO) && !__has_feature(memory_sanitizer)
# define ZEND_USE_ASM_ARITHMETIC 1
#else
# define ZEND_USE_ASM_ARITHMETIC 0
#endif


Missing libcurl errors

swoole/thirdparty/php/curl/curl_interface.h:8:10: fatal error: curl/curl.h: No such file or directory
    8 | #include <curl/curl.h>
      |          ^~~~~~~~~~~~~

You have to install libcurl-dev if you have enabled or set --enable-swoole-curl, for example:

$ sudo apt install libcurl4-openssl-dev


PHP Warning for unable to load dynamic library swoole: php_json_exception_ce

If you receive an error like the following:

PHP Warning:  PHP Startup: Unable to load dynamic library 'swoole' (tried: /usr/lib/php/20190902/swoole (/usr/lib/php/20190902/swoole: cannot open shared object file: No such file or directory), /usr/lib/php/20190902/swoole.so (/usr/lib/php/20190902/swoole.so: undefined symbol: php_json_exception_ce)) in Unknown on line 0

It means you should enable Swoole using phpenmod instead of pasting extension=swoole inside your php.ini file. This error happens because Swoole is trying to load before required modules are even ready. You should use the mods-available directory with your installed PHP to enable Swoole instead. Follow the guides for enabling Swoole and use phpenmod instead. Make sure to also remove extension=swoole from your php.ini file as well.


PHP Warning for Unable to load dynamic library swoole: curl_CURLFile_class

If you get the following error:

PHP Warning:  PHP Startup: Unable to load dynamic library 'swoole' (tried: /usr/lib/php/20190902/swoole (/usr/lib/php/20190902/swoole: cannot open shared object file: No such file or directory), /usr/lib/php/20190902/swoole.so (/usr/lib/php/20190902/swoole.so: undefined symbol: curl_CURLFile_class)) in Unknown on line 0

You need to install the PHP CURL module for the version you have, for example:

$ sudo apt install php7.4-curl


PHP Warning: Cannot load module swoole because module mysqlnd is not loaded

If you get the following error:

PHP Warning:  Cannot load module 'swoole' because required module 'mysqlnd' is not loaded in Unknown on line 0

You need to install the PHP mysqlnd module, for example:

$ sudo apt install php7.4-mysqlnd