User FAQ

What is PEAR?

This is described here.

How do I install a package when I get the error message "No release with state equal to: 'stable' found for 'Packagename'"?

answer by Greg Beaver

The package in question does have releases, but none that are stable. There are two solutions.

  1. Set preferred_state to alpha or beta and then install

    $ pear config-set preferred_state alpha

    $ pear install Packagename

  2. Find out the stability or version number of the latest release and install it directly.

    $ pear install Packagename-alpha

    $ pear install Packagename-1.5.3

Why do I get "No handlers for package.xml version 2.0" when I try to install a package?

You are using a PEAR version lower than 1.4.0.

To install the package, you have to update PEAR via:

$ pear upgrade PEAR

This will install the latest available version of PEAR which is capable of installing packages that have only a package.xml version 2.0.

If you have an old PEAR version installed (i.e. < 1.3.6), you need to use the following commands to install the latest available version of PEAR:

$ pear upgrade --force

$ pear upgrade -a

$ pear upgrade --force PEAR-1.4.11

$ pear upgrade PEAR

There is no end-user documentation for this package! How am I supposed to know how it works?

Even if not all packages do have end-user documentation in the PEAR manual, nearly all of the packages do include examples. The examples are automatically installed when you install a package via the command line installer and are located in $peardir/docs/$packagename/.

You can find the example/documentation directory by executing $ pear config-get doc_dir on command line.

I have a question about PEAR. Where should I ask?

Information on subscribing this mailing lists can be found here.

On all mailing lists mentioned above the language is english and the way you ask questions should always be polite :-).

Does PEAR work on Mac OS X?

answer by Brett Bieber

All Mac OS X versions up until 10.5 come with PEAR by default. Mac OS X 10.5 (Leopard) users will need to install PEAR using the standard installation instructions.

If you are a OS X 10.4 or lower user, you may wish to upgrade to a newer version of PHP using a binary installable package such as Marc Liyanage's PHP packages. If you have installed another PHP package, you may have two versions of PHP and PEAR installed on your system. To be sure which version you are using, type which pear in your console to find out where PEAR is located, and pear -V to find out some info about the pear version, and also pear config-show to see the configuration details.

If you have not made any modifications to the default Max OS X install, the PEAR version you are running is the /usr/bin/pear which is configured for the PHP 4 version distributed with OS X. If this is the case, there are a couple options to use a PHP 5 version on your Mac.

If you're using Marc Liyanage's PHP package, you can specify the full path to your PHP5 PEAR installation. For example /usr/local/php5/bin/pear install {packagename} to install a package for your PHP 5 installation (installing/upgrading packages will probably require sudo).

Alternatively, you can change every path for the OS X provided PEAR using pear config-set. Remember to specify all paths necessary to point to your PHP 5 installation.

What I prefer to do, is remove the Apple supplied PHP 4 with sudo rm /usr/bin/php /usr/bin/pear and then symbolically link php and PEAR in /usr/bin to the location where Marc Liyanage's packages are installed: sudo ln -s /usr/local/php5/bin/php /usr/bin/php && sudo ln -s /usr/local/php5/bin/pear /usr/bin/pear. Keep in mind, Apple occasionally updates PHP on OSX, which will revert your /usr/bin/php to their distributed version. Pay attention to software update, and read the information regarding updated software bundled with OS X updates.

Note: It is uncertain if Apple will continue to distribute PHP version 4 for Mac OS X <= 10.4. So these instructions may change, and may differ for your specific version of Mac OS X. Always consult the Apple documentation to understand the default install provided before making modifications.

Does PEAR work on windows?

To make PEAR work on Windows, you simple need to add the PEAR installation dir (e.g. c:\php\pear) to the include_path directive in your php.ini.

Note: There are some classes (like Schedule/At.php), that do not work on Windows, because they use *nix specific commands.

go-pear.php or bundled packages in the windows build of PHP 4.3.x is out of date!

Unlike other aspects of PEAR development, the windows build of PHP 4.3.x is not tracked in SVN. Instead, it is located on the machine that builds windows snapshots. Often, this will not be updated when the rest of PEAR is updated. Note that PHP 5.x releases use a different build system and are automatically updated to the latest versions of PEAR.

If you find that PHP 4.3.x has out-of-date versions of packages, or no longer works, then please report that the windows bundle of PEAR is out of date to

Why does my browser show strange warnings when logging in to the website?

You are seeing the warnings because uses a SSL key that is signed by CAcert, whose root certificate is unfortunately not bundled with most browsers.

If you are using a Mozilla browser, you can import the certificate on this site by clicking on the link "Root Certificate (PEM Format)". When asked if you want to trust the new Certificate Authority, you need to check at least the "Trust this CA to identify web sites." box and click "Ok".

People using Internet Explorer may find help here.

Mac OS X users must download the above mentioned PEM file. The certificate can then be imported with the "Keychain Access" utility via "Import" in the "File" menu.

Installing into customized windows folders fails

To know that the folder has a customized view, Windows sets the "read-only" attribute to the folder. The "read-only" attribute is not actually used to control write access. You can create files in a "read-only" folder.;en-us;326549

The PEAR Installer detects the read-only attribute and refuses to install into these folders. Unfortunately, there is no way to distinguish between customized folders and actual read-only folders on Windows.

The work-around is to avoid installing PEAR packages into customized Windows folders.

I've got an old installation of PEAR and don't have the permissions to install a new version - what now?

If $ which pear gives you something like /usr/local/bin/pear and $ pear -V shows a very old version or if you don't want to use it for other reasons, you have to install PEAR in your home directory.

Go to, save as gopear.phar and do $ php go-pear.phar.

Use /home/user/pear as prefix while installing PEAR, where user is your username.

Once the installation is done, edit your PATH variable to include your planned new PEAR directory before the old one.

For example put a export PATH=/home/user/pear/bin:$PATH at the end of your ~/.bashrc or ~/.profile under Linux. $ echo $PATH should give you now /home/user/pear/bin:[...]

$ which pear should result in /home/user/pear/bin/pear and $ pear -V something like "PEAR Version: 1.4.8" (at the time of writing) or newer. Check the latest stable version at under Current Release.

Now all you need is to set your include_path correctly, most likely via


I have updated package X to get rid of errors like "undefined function Y", but PHP still shows the error message(s). What's wrong?

It is very likely that you have defined two PEAR directories in your include_path, and that you have updated the package in the directory that is defined behind the first directory in your include_path. If you either remove the wrong directory from your include_path or change the order of the directories in your include_path, the error messages should not be shown anymore.

The downloaded go-pear.phar isn't parsed by PHP! Why?

If you have followed the instructions for getting go-pear.phar and you are using e.g. Windows and the Internet Explorer, you might get the strange effect that -- although you have named the file go-pear.phar -- the file isn't parsed and the PHP source code of it is shown.

The problem is that e.g. the Internet Explorer saves the file as a HTML file with some HTML code around the PHP source code to display the code nicely.

To avoid this problem, you should use the source code view of your browser, e.g. by clicking with the right mouse key and selecting "Show source code" from the context menu. If you save now the file that is shown in your editor as go-pear.php, PHP will be able to parse the file properly.

Please note that the Windows versions of PHP have a file named go-pear.bat bundled. It is recommended to use this batch file on Windows instead of using go-pear.php.

FAQ - Frequently Asked Questions (Previous) Developer FAQ (Next)
Last updated: Sat, 16 Feb 2019 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report.
View this page in:
  • English

User Notes:

There are no user contributed notes for this page.