Checking if PEAR works

Verifying command line tool

Both pear and pecl tools should be available everywhere on command line. For that to work, pear's binary (bin) directory should be in your PATH variable.

To verify it works, simply type pear. A list of commands should be shown:

$ pear
build                  Build an Extension From C Source
bundle                 Unpacks a Pecl Package
channel-add            Add a Channel

You should further test that PEAR is up to date:

$ pear version
PEAR Version: 1.7.2
PHP Version: 5.2.6RC4-pl0-gentoo
Zend Engine Version: 2.2.0
Running on: Linux ...

Verifying the include path

To use PEAR and PEAR compatible packages in your applications, you normally include them into your PHP scripts using require_once(). For this to work, PEAR's php_dir must be a part of PHP's include path.

  1. First, check where PEAR installs .php files:

    $ pear config-get php_dir

    This directory will contain System.php.

  2. Now it's time to find which configuration file is used by your PHP installation. On command line, execute:

    $ php --ini
    Configuration File (php.ini) Path: /etc/php/cli-php5
    Loaded Configuration File:         /etc/php/cli-php5/php.ini
    Scan for additional .ini files in: /etc/php/cli-php5/ext-active
    Additional .ini files parsed:      /etc/php/cli-php5/ext-active/php_gtk2.ini,

    To see which php.ini is used by PHP on your web server, create a file with only <?php phpinfo(); ?> as the contents, and save it in your local web root as check_php.php. Open the file in your browser as http://localhost/check_php.php, to find the path to the php.ini file your web server is using.

  3. Now check PHP's include_path setting on command line:

    $ php -c /path/to/php.ini -r 'echo get_include_path()."\n";'

    To check PHP's include_path in your web server, create a file with only <?php phpinfo(); ?> as the contents, and save it in your local web root as check_php.php. Open the file in your browser as http://localhost/check_php.php, to verify the include_path your web server is using.

    In every case, PEAR's php_dir should be in the include path. If not, add it in your system's php.ini.

  4. Now that this is done, try including a file. Create a new check_pear.php file with the following contents:

    require_once 'System.php';

    System.php is shipped with every PEAR installation and thus should be on your computer, too. Open the file with the browser from your web server, and also try it on command line. The only output should be


    A message like:

    Warning: require_once(System.php): failed to open stream:
     No such file or directory in /path/to/check_pear.php on line 2

    means that your include path is not correct. (So go and fix it!)

    A completely white page in your browser hints two things:

    • Your server is configured to not display any errors to the user/browser (display_errors Off)

    • There was an error including System.php, and you should check you server's error log.

That's it! Now go on and install some packages.

Things that could be in your way

  • After changing php.ini, you need to restart your web server.

    Few people also reported they had to restart the whole machine physically, probably due to PATH changes not propagating correctly. Before wasting hours and after you tried everything else, just try that.

  • Newer Linux distributions use multiple php.ini files; mostly one for the web server (e.g. /etc/php/apache2-php5/) and one for command line (like /etc/php/cli-php5/). Make sure you edit the right ones.

  • On Windows, recent versions of PHP use php.ini from their own directory (where php.exe is). You still might have an old php.ini in your windows or system(32) directory that fools you.

  • You cannot get away with using absolute paths in your own require_once() statements as an altervative to fixing your include_path, because all the other files that are then required by your scripts are all coded for relative pathing based on include_path.

Modifying php.ini

To get PEAR working properly, you need to adjust PHP's include_path. After you found php.ini, open it in an editor.

Search for the line include_path.

Now that you found it, you probably will see a semicolon ; at the beginning. This means the line is a comment. Add a new line below it.

In this line, write:


Depending on your operating system, add a : (Unix/Linux/FreeBSD/Mac OS X) or a ; (Windows) after the dot. Add PEAR's php_dir after it. (The directory System.php is located in!)

The result should look like that:

; Unix


; Windows
Installation of a local PEAR copy on a shared host (Previous) Command line installer (PEAR) (Next)
Last updated: Thu, 26 Nov 2015 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

Note by:
So after some great fudging around I solved my problem.

The System file for me was /share/pear so I had to include include_path=".:/share/pear" in php.ini I then restarted Apache and found the check_pear.php file wasn't searching the path I specified.

So I did a search and found in etc/php5/apache2/ there was also a php.ini file and that file was being used over the php.ini in the PHP directory.

Once I included the path in that file it worked.
Note by:
This is the most unintuitive install documentation I've ever seen.


Where is the php directory.
Typing perl doesn't work...
wget ok...
php is installed but php: command not found...

grrrrr. Am I the only person having problems with linux.

<Pulls hair out>
Note by:
I think you need to run sudo -s to run anything but pear (like pear list, install to get updates, new packages, etc) at least in OS X
Note by:
on IIS 5.1 (believe also for IIS 6)

after changing registry files to point to new location

changing the enviaroment variables under

my computer icon+'RightClickMouse'>choose properties > new window = System Properties >choose tab-Advanced > choose-enviaroment variables button >new window = enviaroment variables >

on upper section - User variables for ....=[loginadminuser]

chose PATH under the list and 'Edit' button
on my system the path variable was set to= ;;S
so i edit it to include my path + the default setting
result turned to this=


just to make sure - i added this path also for the system Variables section on that window...

then tried the pear command on command prompt and got a response like PHP_PEAR_PHP_BIN not set correctly on the pear.bat file - default value set to .\php.exe

located the file on the dir i installed php on > rightclickmouse and choose edit

found the line setting the value and change it to the location of the php.exe file final result of that line looks like this:

IF "%PHP_PEAR_PHP_BIN%"=="" SET "PHP_PEAR_PHP_BIN=C:\Inetpub\wwwroot\php\php.exe"

hope i helped you guys running also on old computer and system.... :)

Note by:
In some cases the "System.php" is located in "/usr/share/php" not "/usr/share/php/pear" where PEAR resides - if you still get a blank page or have troubles, just inlcude "/usr/share/php" in php.ini

I also experienced troubles with including "/" at the end of the path "/usr/share/php/", after removing the "/" like that "/usr/share/php" everything worked fine.
Note by:
"Warning: require_once(System.php): failed to open stream:
No such file or directory in /path/to/check_pear.php on line 2"
might also mean that the installation was chmoding the files to rw-------.
sometimes the umask config gets set to 77 if you are logged in as root when running go-pear. change the umask to 22
pear config-set umask 22
fixes this I guess I shouldn't install go-pear as root.
Note by:
My English isn't very well, maybe some can translate:
Es ist möglicherweise nicht ausreichend, die Systemdateien in /etc/path/to php.ini zu editieren, denn diese Voreinstellungen werden durch andere Werte in anderen dominanten Konfigurationsdateien möglicherweise überschrieben.

Wichtig ist der Hinweis mit open_basedir , auch wenn die Lösung des Problems tückisch und schwieriger zu finden ist, als man es hier liest.
Die Pfade können natürlich von System zu System abweichen.
Bei meinem Debian-System sind weitere Konfigurationsdaten vorhanden, die dominant die Mastereinstellungen überschreiben. Diese sind in der Datei
$ /var/www/vhosts/<hostname>/conf/http.include

Es ist also *nicht* immer ausreichend, in der php.ini den Wert
open_basedir =
einzufügen, denn dieser dort gespeicherte Wert wird durch einen in der Datei http.include gespeicherten Wert überschrieben.

Unter den Abschnitten <IfModule mod_php4.c> und <IfModule mod_php5.c> einfach den Pfad der System.php -Datei eintragen, die Pear erstellt hat:

Das schaut dann so etwa aus:
<IfModule mod_php4.c>
php_admin_flag engine on
php_admin_flag safe_mode off
php_admin_value open_basedir ".:/usr/share/php/:/var/www/vhosts/<hostname>/httpdocs/"
<IfModule mod_php5.c>
php_admin_flag engine on
php_admin_flag safe_mode off
php_admin_value open_basedir ".:/usr/share/php/:/var/www/vhosts/<hostname>/httpdocs/"

Ob sich hierdurch Sicherheitsrisiken auftun weiß ich nicht, ich denke nicht.
Jedenfalls läuft hierdurch PEAR einwandfrei.
Note by:
There's a problem with the location of php.ini :
With the command line php --ini, location of php.ini is under the directory c:\wamp\bin\php... but when you change the include_path at this location, nothing append. But when you verify at your phpinfo(), you can see immediately tht the location of php.ini tht wha's loaded is surprisely, in the bin of apache.
so the real php.ini is under the directory of apache.
One other details : I installed apache with php at the same time, so perhaps it's the reason why.
PS: for the webmaster... please, i don't write good in english, so, if you can transform this message in a good english... thank you
Note by:
It is important to note that if you have open_basedir specified in your PHP and/or Apache configuration, you will need to include the path to your PEAR packages in the open_basedir path or your includes will fail.

The open_basedir directive restricts what directories can be used for local includes. It is chiefly a security measure against injecting malicious includes (though there are flaws that some have called unrepairable in the security of this mechanism).

You can change the open_basdir directive for php.ini or you can specify php_admin_value open_basedir in your Apache http.include file (which will take precedence over the value in php.ini).

This took me a good deal of sniffing around to figure out myself as I didn't find it documented anywhere else alongside information dealing with PEAR or issues with including packages. I hope this will save someone some time :)
Note by: cweiske
When you get a blank screen from apache, you should check the error log for fatal php errors.
Note by: cweiske
When you are on a shared host and cannot influence php.ini, use

at the beginning of your application.