JavaScript Editor Javascript validator     Web page editor 

Installing packages

After getting PEAR working on your machine (see Installation) you most likely want to install some packages. This guide shows people new to the PEAR command line installer how to get started.

Normal installation procedure

The general command to install a PEAR package named "foo" is

$ pear install foo

Typing this and pressing return, the package will be downloaded and installed on your computer. It does not matter if you write the package name in lowercase, UPPERCASE or MixedCase - the installer will find the package by lowercasing the name.

When a package is already installed, you will get the following message:

$ pear install foo
Ignoring installed package pear/foo
Nothing to install

This happens even if there is a newer version of the package! The correct command to upgrade to the lastest version is

$ pear upgrade foo
upgrade ok: channel://

If the package already has the lastest version, you will get a message similar to the following:

Ignoring installed package pear/Foo
Nothing to upgrade

In the case you deleted some file and really really want to re-install the package, you have two choices:

Forcing an command should only be done when you absolutely know what you are doing - you might in some circumstances break PEAR otherwise. Forcing something should always be the last option.

$ pear install -f foo
$ pear upgrade -f foo

Unstable alpha/beta packages

Now and then, you will get error messages like

Failed to download pear/foo within preferred state "stable",
 latest release is version 0.1.2, stability "beta",
 use "channel://" to install
Cannot initialize 'channel://', invalid or missing package file
Package "channel://" is not valid
install failed

Reason for this is that PEAR by default installs stable packages only. When a package is in state devel, alpha or beta it will refuse to install them. You can easily persuade it by adding either the version number or the stability you are willing to accept:

$ pear install Foo-beta
$ pear install Foo-alpha

You can also install a specific version, or upgrade to a specific version regardless of the state:

$ pear install Foo-1.2.3
$ pear upgrade Foo-1.2.3


A package often requires other packages to be installed to function correctly. Such a relation is called a dependency. The PEAR installer has full support for dependencies; it can automatically install required and/or optional dependencies if you wish so.

If you try to install a package with required dependencies, you will get an error that the installation failed. Looking deeper and actually reading the messages shows you that the package needs dependencies that are not installed on your system:

$ pear install html_page2
Did not download dependencies: pear/HTML_Common,
 use --alldeps or --onlyreqdeps to download automatically
pear/HTML_Page2 requires package "pear/HTML_Common" (version >= 1.2)
No valid packages found
install failed

You have several choices:

The first method can be a painful and daunting process, because dependent packages itself can have dependencies.

Both other methods just require a switch to the install command, either --onlyreqdeps (install required dependencies only) or --alldeps (install all dependencies).

$ pear install --onlyreqdeps html_page2
WARNING: "pear/HTML_Common" is deprecated in favor of "pear/HTML_Common2"
downloading HTML_Page2-0.5.0beta.tgz ...
Starting to download HTML_Page2-0.5.0beta.tgz (15,467 bytes)
......done: 15,467 bytes
downloading HTML_Common-1.2.4.tgz ...
Starting to download HTML_Common-1.2.4.tgz (4,519 bytes)
...done: 4,519 bytes
install ok: channel://
install ok: channel://

Offline installation

You can download individual packages for e.g. offline installation on a second machine just as you would install or upgrade a package:

$ pear download Foo

After downloading, you will have a file like Foo-1.2.3.tgz if the latest version of Foo was 1.2.3. Installing it is as easy as typing

$ pear install Foo-1.2.3.tgz

Manual package installation


We removed this section, because, today, manually installing a package requires a deeper understanding of the way how packages are organized and what happens during the installation process. You should read the section about the package.xml in the Developers Guide (Chapter 20 and Chapter 21), if you really want install a package without the PEAR installer.

If you want to install PEAR on a remote host without shell access, you should look into the Section called Installation of a local PEAR copy on a shared host in Chapter 10.

Installing packages from CVS

This passage will describe how to install the latest development version of a PEAR package from CVS.

It is NOT recommended to run a package from CVS in working environments! Because CVS versions are not regular releases, this means:

You should use a package from CVS only, if:

If you still want to install a package from CVS, you have to do the same steps like a package maintainer creating a new release of a package. If you have problems following the next steps, take a look into the Developers Section of the manual.

  1. Get the package files from CVS like described in

    The name of the module to checkout is pear/<packagename>, i.e. cvs -d checkout pear/HTTP_Client.

  2. Check the package.xml file, especially the dir and file entries. They must match the existing files and directory structure. If they differ, contact the package maintainer and ask for an update of the package.xml.

  3. Create a valid package using the PEAR Installer pear package <path to package.xml>

  4. If you have already installed the package: remove it to avoid version conflicts: pear uninstall <package>

  5. Install your package archive: pear install <package-file>

    Now, you have a CVS version installed!

You should upgrade to an official release of the package as early as possible. Before you install the official release, uninstall the CVS version to avoid version conflicts.

Installing PECL packages

The procedure of installing PECL packages is described in the pecl manual section on the PHP website.

JavaScript Editor Javascript validator     Web page editor