How-To: Compiling XCache from Source

January 30, 2007 by · 27 Comments 

For those of you that are not running RPM-based distros, you're probably feeling a bit left out. Up until now, all of my tutorials have dealt with upgrading RPM-based distros. Well, that ends here. I'm going to walk through the fairly simple process of compiling and installing XCache for httpd from the original source.

The current stable release of XCache is 1.0.3. The "Unstable" release, made for PHP 5.1 & 5.2, is 1.2.0. Despite the label, I have not found anything "unstable" about the 1.2.0 version. That said, there have been a few issues reported on the vBulletin forums for users of PHP 4. If you are running PHP 4, I'd recommend that you use 1.0.3, just to be safe. Now, down to the work.

Assuming that you already have a full development environment on your system (gcc, gcc-c++, make, php-devel, etc.), the first thing you'll need to do is to download the source tarball to your computer. Pick the version you want and then continue to the next step.

Once you've downloaded the source pacakge to your server, unpack it and then enter the "xcache" directory that was just created. At this point, you'll want to run the following commands. Even a slow system should be done within 1 or 2 minutes, so don't go anywhere.

  • phpize
  • ./configure --enable-xcache
  • make
  • make install

NOTE: There are supposed to be two (2) "-" characters before "enable-xcache" but WordPress seems to be mangling them...

The output of "make install" is very important as it lets you know where the compiled module was installed. Make sure that you remember or write down that string.

Now that the module is installed, you'll need to configure it. If your install of PHP parses the /etc/php.d/ folder then you should create a file in that folder called "xcache.ini". If not, just open your php.ini file and paste in the following:

zend_extension = /usr/lib/php4/

; required for >=php5.1 if you turn XCache on
auto_globals_jit = Off

xcache.admin.user = "admin"
; paste the output of md5("password") below
xcache.admin.pass = ""

xcache.size = 32M
xcache.count = 1
xcache.slots = 8K
xcache.mmap_path = "/dev/zero"
xcache.cacher = On

Based on your configuration, you may want to make a few changes. If "/usr/lib/php4" was not where "make install" claimed to have installed the module, change it. Likewise, if your system has multiple processors (count logical cores from Hyper-Threading), change the value of "xcache.count". Finally, if you plan to use the web admin interface, you'll need to fill in "xcache.admin.pass". This value should be a MD5 of the password you want to use (if you need an MD5 generator, try this one).

If you filled in the password, you should also copy the contents of the "admin" folder from the "xcache" source folder to somewhere web-accessible. No changes need to be made and the "config.php.example" file should be left as-is.

At this point, all that's left is to restart httpd and you should be good. Check your phpinfo() once you've restarted httpd to make sure that xcache is listed.

UPDATE: Version 1.2.x is now considered "stable" and the current release is up to 1.2.1.


27 Responses to “How-To: Compiling XCache from Source”
  1. Jarod says:


    Im on plesk and i have a problem with phpize, how can I activate or install it?

    Thank you đŸ™‚

  2. Jason says:

    Install the 'php-devel' package.

  3. Matt says:

    Hey Jason,

    Firstly, thanks for your great guides!, and I hope you can help me out.

    For the last week or so, I have spent a long time trying to install APC, eaccelerator, and now XCache.

    I am running a CentOS4.4 from mediatemple ( I have managed to build the *.so files but yet they do not load properly. I think this might be from an error when I run phpize.

    On the XCache package when running "phpize" I recive the following error.

    [[email protected] xcache]# phpize warning: underquoted definition of PHP_WITH_PHP_CONFIG
    run info '(automake)Extending aclocal'
    or see warning: underquoted definition of PHP_EXT_BUILDDIR warning: underquoted definition of PHP_EXT_DIR warning: underquoted definition of PHP_EXT_SRCDIR warning: underquoted definition of PHP_ALWAYS_SHARED
    acinclude.m4:19: warning: underquoted definition of PHP_PROG_RE2C
    /usr/share/aclocal/libgcrypt.m4:23: warning: underquoted definition of AM_PATH_LIBGCRYPT
    Configuring for:
    PHP Api Version: 20020918
    Zend Module Api No: 20020429
    Zend Extension Api No: 20021010

    I think it might be something to do with libtool / libgcrypt, but im not sure. Im a total centos / linux newbie :/. I tried to install libgcrpyt, I think I did but in not too sure.

    Also, last question, when I type "php -v" I receive the message.

    PHP 4.3.9 (cgi) (built: Nov 7 2006 05:00:50)
    Copyright (c) 1997-2004 The PHP Group
    Zend Engine v1.3.0, Copyright (c) 1998-2004 Zend Technologies

    I hope as it says cgi this is okay, I read about fcgi.

    I am sorry to bombard you with all this Jason, but im very much stuck, and hoping you can help me out.

    Thanks very much.

  4. Jason says:

    Warnings are OK, errors are not. What happens when you run "make"? Does it compile without errors? How about "make install"? It should tell you where it was installed. Once it does, you should verify that the file is actually there and make sure that the code I pasted in the post references the correct path.

    Assuming that you don't have any errors at that point you might want to check your phpinfo() from a web page as sometimes there are different config files for the different binary versions of PHP.

  5. Matt says:

    Many thanks for your reply Jason. Interestingly enough, I was watching for errors and I didn't see any, and this time it worked. That makes no sense as it's exactly what I did the last time and for APC.

    I have noticed something strange though, when I increase the size, it throws an error, httpd do not spawn and i said something about shm error. When the size is at 32mb it is fine.

    But I am filling up my cache in about 2mins, and all I get now are clogs. If I can increase my space somewhat I will, but I think it will get full quickly. Is there a way to remove less frequently used files or a time limit? I saw the TTL setting, but am not sure what would be a good value.

    Can I try 1.2.0 or is that only for php5? im running 4.3.9. Many thanks for the help Jason

  6. Matt says:

    Sorry to spam your comments like this, feel free to delete đŸ™‚

    I updated the version, and all looks good so far. im getting clogs, but a lot less, and the hits continue to rise now.
    54,000 hits to 4,000 misses.

  7. Jason says:

    Clogs occur when multiple files need to be inserted into the cache at the same time. These are normal for the first couple minutes after startup.

    As to the misses, that is not normal unless you have 4000 files (because each file cached is a miss the first time around).

    Regarding your problem with caching more than 32MB, what is xcache.count set to? You might try increasing that at the same time as you increase the size (there may be some kind of allocation limit on your system).

    Finally, as to TTL, you'd want to set xcache.ttl to the upper limit on stale cache entries and then xcache.gc_interval to a number in the range of 1/4-1/2 of ttl (I use 900 & 300 respectively).

  8. Matt says:

    Thanks for the great info Jason. I think there was a problem with XCache 1.0.3 for me, the 32mb limit and rising clogs and frozen hits.
    With 1.2.0 things seem well. I have the size set on 80mb, this is giving me current stats of 487,935 hits, 28,360 Misses. My cache is 100% full giving me 816 cached files and 27,543 OOMs.
    I guess I would need to increase my cache size even more to cache the other files and give me less misses / OOMs, but I think 80mb is max for my server ram. The hit / miss ratio seems nice enough for me, and server load has dropped.
    As for your question my xcache.count is currently set to 1.
    Thank you for the information about TTL I was curious as to what good settings would be for this, I will try your recommended settings.

  9. Curtis says:

    PHP Fatal error: Failed creating file mappping in Unknown on line 0
    PHP Fatal error: XCache: Cannot create shm in Unknown on line 0
    PHP Fatal error: XCache: Cannot init in Unknown on line 0
    PHP Fatal error: Unable to start XCache module in Unknown on line 0

    Any idea why I get this error when I try
    php-cgi -v

    And when I look at it does not show that it parses xcache.ini

    Please help

  10. Jason says:


    If you are using PHP 5.2 then you should be using 1.2. PHP 4 users can try 1.0.3. As to the high number of OOMs you've received, I'd say that you need to either increase the memory limit or change the TTL value to remove unused entries.


    That's really not enough info to go on. Some PHP installs have different ini files for the different binary packages. Some also don't parse external ini files (like the one provided in my src.rpm). Try copying the content from your xcache.ini file directly into the php.ini file that is referenced in a phpinfo().

  11. Josech says:

    In which directory do i have to unpack xcache? im newbie in linux

  12. Josech says:

    [[email protected] xcache]# phpize
    bash: phpize: command not found

  13. Josech says:

    Ok, done with "yum install php-devel" đŸ™‚

    But now:

    [[email protected] xcache]# ./configure –enable-xcache –enable-xcache-optimizer
    configure: WARNING: you should use --build, --host, --target
    configure: WARNING: invalid host type: –enable-xcache
    configure: WARNING: you should use --build, --host, --target
    configure: WARNING: invalid host type: –enable-xcache-optimizer
    checking build system type... Invalid configuration `–enable-xcache': machine `–enable' not recognized
    configure: error: /bin/sh ./config.sub –enable-xcache failed
    [[email protected] xcache]#

  14. Josech says:

    Finally worjked eith:
    $ ./configure --enable-xcache

  15. Lazydesis says:

    Thanx a lot .. i justinstalled at my site

    will reply back again if i see any performance increase

  16. Manuel says:


    I am getting the following error while giving the command ./configure –enable-xcache. I am using php 5.2.3 and am compiling xcache from source.

    [email protected] [/usr/src/xcache]# ./configure –enable-xcache
    configure: WARNING: you should use --build, --host, --target
    configure: WARNING: invalid host type: –enable-xcache
    checking for egrep... grep -E
    checking for a sed that does not truncate output... /bin/sed
    checking for –enable-xcache-gcc... no
    checking for gcc... gcc
    checking for C compiler default output... a.out
    checking whether the C compiler works... yes
    checking whether we are cross compiling... no
    checking for suffix of executables...
    checking for suffix of object files... o
    checking whether we are using the GNU C compiler... yes
    checking whether gcc accepts -g... yes
    checking for gcc option to accept ANSI C... none needed
    checking whether gcc and cc understand -c and -o together... yes
    checking if compiler supports -R... no
    checking if compiler supports -Wl,-rpath,... yes
    checking build system type... Invalid configuration `–enable-xcache': machine `–enable' not recognized
    configure: error: /bin/sh ./config.sub –enable-xcache failed

    Any help would be appreciated.

    Thank you

  17. Jason says:

    Make sure that you're passing "--enable-xcache" with two "-" at the front, not just one. I think WordPress screws those up so I'll add a little note up in the post.

  18. Dale says:


    We have tried installing the latest version of Xcache onto a client's VPS server for them.

    We followed all the instructions at:

    Now if we run a php -v, we get the following output:

    PHP 5.2.3 (cli) (built: Aug 23 2007 20:21:09)
    Copyright (c) 1997-2007 The PHP Group
    Zend Engine v2.2.0, Copyright (c) 1998-2007 Zend Technologies
    with Zend Extension Manager v1.2.0, Copyright (c) 2003-2006, by Zend Technologies
    with Zend Optimizer v3.2.2, Copyright (c) 1998-2006, by Zend Technologies

    Xcache does not seem to be running?

    If we try to run/use admin via HTTP, we cat the following:

    XCache is not loaded
    Please check /usr/local/Zend/etc/php.ini

    Could you explain what we might be doing wrong? or where we should be looking?


    Dale Evans

  19. Jason says:

    Have you checked your php.ini file to see if the xcache config entries are in there? Have you verified that the path specified in the php.ini to load the extension is correct? Are there any errors in your httpd error_log? Have you tried disabling the Zend Optimizer to see if XCache loads properly then? If so, try loading XCache before Zend.

  20. Xem Phim Online says:

    Thank you, Jason,

    I tried many tutorial but yours is the best.

    It helped me to install Xcache properly on my new site:

    I see good amount of load reduce,

    Thanks Jason, Thanks Xcache đŸ˜‰

  21. Gizmo says:


    checking for dlfcn.h... yes
    checking for g++... no
    checking for c++... no
    checking for gpp... no
    checking for aCC... no
    checking for CC... no
    checking for cxx... no
    checking for cc++... no
    checking for cl... no
    checking for FCC... no
    checking for KCC... no
    checking for RCC... no
    checking for xlC_r... no
    checking for xlC... no
    checking whether we are using the GNU C++ compiler... no
    checking whether g++ accepts -g... no
    checking how to run the C++ preprocessor... /lib/cpp
    configure: error: C++ preprocessor "/lib/cpp" fails sanity check
    See `config.log' for more details.

  22. Jason says:


    Looks like you don't have a compiler installed. Check the 'config.log' file for more info.

  23. rgouveia says:


    great tutorial, but im getting the following error in apache error_log:

    Failed loading /home/xpto/data/lib/php/ /home/xpto/data/lib/php/ undefined symbol: OnUpdateInt

    Any idea of what might been wrong?


  24. rgouveia says:

    phpize --clean seems to work on a clean new build.

  25. Xem Phim says:

    You may need to check the C++ compiler

  26. Alex says:

    Thanks for the info...I just installed on my site and will let you if the performance has increased or not...


Check out what others are saying about this post...
  1. Filecache OR Xcache - vBulletin SEO Forums says:

    [...] If you have 'vB_Datastore_XCache' defined in your config.php and your forum is still loading then its working. You can also use xcache's web admin interface. Guide here: How-To: Compiling XCache from Source at Utter Ramblings [...]

This site is no longer updated. If you have a need for RHEL/CentOS LAMP Stack updates outside the normal channels, I recommend ART.