Installing PEAR



The PHP Extension and Application Repository, or "PEAR", is a repository of reusable PHP code which you can add to your website to easily enable certain functions such as SMTP Mail.

Various packages can be downloaded from the PEAR repository, at:

The following information walks you through the following:

  • How to set up your DreamHost environment to run PEAR.
  • How to download and install the packages.

PEAR MAIL compared to PHPMailer

Both PEAR MAIL and PHPMailer allow you to send email using SMTP. But there are a few reasons why PHPMailer may be a better choice. For example:

  • PEAR MAIL cycles the socket connection for each message. This could potentially cause the connection to be caught by DreamHost's servers as a brute force attempt.
  • PHPMailer open a socket only once. The socket is then kept open as it processes messages.
  • PHPMailer is very well documented with many online examples and help pages.
  • PHPMailer integrates well with Google's SMTP servers.

For these reasons, PHPMailer is worth taking a look at as an alternative to PEAR MAIL.

Installing PEAR manually

PEAR is not installed by default on DreamHost servers. If you require any PEAR package to operate on your site it must be installed manually using the following steps.

  1. Make sure the user assigned to your domain is a SHELL user. Visit the following article which explains how to set up your SHELL user:
  2. Once the user is a SHELL user, log into the web server via SSH. Visit the SSH article for instructions on how to log into your server depending on which operating system you are using:
  3. Once you’ve logged into your server, make sure you're in your user's directory. Run these commands in your SHELL terminal:
    [server]$ cd ~
    [server]$ pwd 
    • User is named username.
    • In this example, you can see you're in the user's directory because the full path is /home/username.
  4. Make a temporary directory. This will be used in the following steps when installing.
    [server]$ mkdir -p pear/tmp/pear/install
  5. Run the following wget command to download the go-pear.phar file to your user's directory:
    [server]$ wget
  6. Run the file by entering this command in the same directory:
    [server]$ /usr/local/php74/bin/php go-pear.phar
  7. During the install process, provide the following responses at the prompts:
    [server]$ /usr/local/php74/bin/php go-pear.phar
    Below is a suggested file layout for your new PEAR installation. To
    change individual locations, type the number in front of the
    directory. Type 'all' to change all of them or simply press Enter to
    accept these locations.
     1. Installation base ($prefix)                   : /home/username/pear
     2. Temporary directory for processing            : /tmp/pear/install
     3. Temporary directory for downloads             : /tmp/pear/install
     4. Binaries directory                            : /home/username/pear/bin
     5. PHP code directory ($php_dir)                 : /home/username/pear/share/pear
     6. Documentation directory                       : /home/username/pear/docs
     7. Data directory                                : /home/username/pear/data
     8. User-modifiable configuration files directory : /home/username/pear/cfg
     9. Public Web Files directory                    : /home/username/pear/www
    10. Tests directory                               : /home/username/pear/tests
    11. Name of configuration file                    : /home/username/.pearrc
    1-11, 'all' or Enter to continue:
  8. You should change the location of the tmp directories. Type 2 and press Enter.
    (Use $prefix as a shortcut for '/home/username/pear', etc.)
    Temporary directory for processing [/tmp/pear/install] : /home/username/pear/tmp/pear/install
    Change the username to your actual Shell username in the command above.
  9. Press Enter to save and proceed.
  10. The list appears again. This type 3 and press Enter.
    (Use $prefix as a shortcut for '/home/username/pear', etc.)
    Temporary directory for downloads [/tmp/pear/install] : /home/username/pear/tmp/pear/install
    Change the username to your actual Shell username in the command above.
  11. Click Enter to save and proceed.
    WARNING!  The include_path defined in the currently used php.ini does not
    contain the PEAR PHP directory you just specified:
    If the specified directory is also not in the include_path used by
    your scripts, you will have problems getting any PEAR packages working.
    Would you like to alter php.ini </etc/php74/php.ini>? [Y/n] :
  12. Type in Y and press Enter.
    WARNING: Cannot write to /etc/php74/php.ini, but php.ini was successfully created
    at </home/username/pear/php.ini-gopear>. Please replace the file </etc/php74/php.ini> with
    </home/username/pear/php.ini-gopear> or modify your php.ini by adding:
    Current include path           : .:
    Configured directory           : /home/username/pear/share/pear
    Currently used php.ini (guess) : /etc/php74/php.ini
    Press Enter to continue:
  13. Click Enter again to proceed.
    The 'pear' command is now at your service at /home/username/pear/bin/pear
    ** The 'pear' command is not currently in your PATH, so you need to
    ** use '/home/username/pear/bin/pear' until you have added
    ** '/home/username/pear/bin' to your PATH environment variable.
    Run it without parameters to see the available actions, try 'pear list'
    to see what packages are installed, or 'pear help' for help.
    For more information about PEAR, see:
    Thanks for using go-pear!
    The include_path will be set in the following steps.
  14. View the creating and editing a file via SSH article for instructions on how to edit your existing .bash_profile. You’ll see these lines already in that file:
    # ~/.bash_profile: executed by bash(1) for login shells. 

    umask 002
    PS1='[\h]$ '
  15. At the bottom, enter these two lines:
    export PHP_PEAR_PHP_BIN=/usr/local/php74/bin/php
    export PATH=${HOME}/pear/bin:/usr/local/php74/bin:${PATH}
  16. Save and close the file and return to your shell.
  17. Run the following command to allow your current Shell session to use PEAR:
    [server]$ . ~/.bash_profile

You've now installed PEAR – but for your environment to know where to find this installation, you must set up the include_path within your phprc file.

Setting the include_path in your phprc file

If you do not set up this include_path correctly, you may find your installation does not work as intended.

  1. Update your phprc file to allow PHP to know where to look for the PEAR install. View the following articles for instructions on how to create a phprc file: If the file already exists, view the following article for instructions on how to update it:
  2. Update the phprc file with the following command:
    include_path = ".:/home/username/pear/share/pear"
    • Change username to your actual Shell username that the domain is under.
  3. Navigate back to your user's directory.
    [server]$ cd ~
  4. Once there, run pear list to see if you get a response:
    [server]$ pear list
    Installed packages, channel
    Package          Version State
    Archive_Tar      1.3.12  stable
    Console_Getopt   1.3.1   stable
    PEAR             1.9.5   stable
    Structures_Graph 1.0.4   stable
    XML_Util         1.2.3   stable

Since you receive a response, you can see that PEAR is now functioning.

Changing the /tmp cache directory

When you installed PEAR above, you manually set the location of the tmp directories. You should also update the location of the cache directory to this temp location.

Run the following to view the current /tmp directories:

[server]$ pear config-show | grep cache_dir
PEAR Installer cache directory cache_dir        /tmp/pear/cache

Run the following to update the cache tmp directory. Change username to the shell user you're currently running the command under.

[server]$ pear config-set cache_dir /home/username/pear/tmp/
config-set succeeded

Installing packages

You are now able to install any packages you like using the pear command. For example, run the following to install the mail package:

[server]$ pear install --alldeps Mail
  • The -onlyreqdeps flag instructs the installer to install only required dependencies.
  • Visit for a list of available packages.

If you see any errors when attempting to install, view the following article for possible solutions:

Confirming your PEAR environment settings

To see if your environment is correctly set, run the following commands in your user's directory:

To determine which PHP (local or shared) command will be used:

[server]$ which php

To determine which PHP version is being used:

[server]$ php -v

To determine which PEAR (local or shared) command will be used:

[server]$ which pear

To determine which PEAR version is being used:

[server]$ pear -V

Use this command to display all your PEAR settings – your local configuration data should display:

[server]$ pear config-show


View the following article for troubleshooting examples:

Example of a PHP SMTP mail script

View the following article for an example of how to send PHP mail via SMTP.

See also

Did this article answer your questions?

Article last updated PST.

Still not finding what you're looking for?