Installing EDirect

To get started with EDirect, you need three things:

1. A Unix command line environment…
2. With the Perl programming language installed, so you can execute…
3. The EDirect installation package

Once you have installed EDirect, you can:

• Test your EDirect installation
• Update to the newest version of EDirect

Unix command line environment

Unix is a simple operating system for issuing instructions to a computer. Before graphical user interfaces like Microsoft Windows or Mac OS X, any user who wanted to interact with a computer would have to type their instructions into a command line interface.

Although we now have other ways of interacting with a computer, using a command line interface (also called a “terminal emulator” or “terminal”) is still a powerful and flexible way of telling a computer what to do. If you are using a Mac or Linux computer, you already have a Unix command line environment ready to go! However, if you are using a Windows computer, you may need to install software to emulate this Unix environment.

One way you can get a Unix terminal in Windows is to install Cygwin. This open-source software lets you interact directly with your computer by typing instructions into a command line. Once you have installed EDirect, this software will also recognize EDirect commands which let you search, download, and re-format PubMed and other NLM data. If you do choose to use Cygwin, you will need to make sure you include the Perl programming language in your installation (see below).

Perl programming language

In order to install the EDirect software, you will need to make sure that the Perl programming language is installed on your system. While you don’t necessarily need to know Perl in order to use EDirect, the EDirect installation process uses some Perl commands.

The Mac Terminal and many Linux distributions come with Perl pre-installed. If you are using Windows, you will need to make sure that the software you are using to emulate the Unix environment has Perl installed. If you are using Cygwin to emulate Unix, the Cygwin installer will offer you a large variety of tools that you can install with Cygwin, including programming languages like Perl and Python, and many different utilities.

When you install Cygwin, you can choose which languages and utilities to install on the “Select Packages” page of the installer. To make sure you have all necessary Perl packages, make sure that “Category” is selected in the “View” drop-down menu at the upper left, then find the “Perl” category in the list. In order to install all Perl packages, click on the circle-with-arrows icon (just to the right of the word “Perl”) until the label next to it switches from “Default” to “Install”. If you previously installed Cygwin without the required packages, you can re-run the installer to add additional packages to your installation.

EDirect installation

To install EDirect, open your Unix terminal and execute the following commands. (The easiest way to do this is to copy the whole block and paste it directly into your terminal window.)

cd ~
/bin/bash
perl -MNet::FTP -e \
    '$ftp = new Net::FTP("ftp.ncbi.nlm.nih.gov", Passive => 1);
    $ftp->login; $ftp->binary;
    $ftp->get("/entrez/entrezdirect/edirect.tar.gz");'
gunzip -c edirect.tar.gz | tar xf -
rm edirect.tar.gz
builtin exit
export PATH=$PATH:$HOME/edirect >& /dev/null || setenv PATH "${PATH}:$HOME/edirect"
./edirect/setup.sh

This installs the EDirect software and gets it ready to use. Depending on your system’s configuration, you may see the following message:

In order to complete the configuration process, please execute the following:

followed by a command that looks something like:

echo "export PATH=\$PATH:\$HOME/edirect" >> $HOME/.bash_profile

If you see this prompt, copy the command provided and paste it into your terminal.

Once the installation is complete, you will see the following message in your terminal window:

Entrez Direct has been successfully downloaded and installed.

You can confirm EDirect is installed correctly by using the testing script below.

Test your EDirect installation

To confirm that EDirect is installed and working properly, you can run your first EDirect script! Just type (or copy and paste) the following code into your terminal window, and press Enter.

echo "***********************" > installconfirm
echo "esearch version:" >> installconfirm
esearch -version >> installconfirm
echo "xtract version:" >> installconfirm
xtract -version >> installconfirm
echo "EDirect install status:" >> installconfirm
esearch -db pubmed -query "Babalobi OO[au] AND 2008[pdat]" | \
efetch -format xml | \
xtract -pattern Author -if Affiliation -contains Medicine \
-element Initials >> installconfirm
echo "***********************" >> installconfirm
cat installconfirm
rm installconfirm

The result should be a message similar to the following:

***********************
esearch version:
10.9
xtract version:
10.9
EDirect install status:
OK
***********************

If you see this output, you have installed EDirect successfully!

However, if your esearch or xtract version are earlier than the number stated above, you may need to update to the latest version of EDirect. If your output does not resemble the above sample (e.g. your esearch and xtract versions do not match, you get an additional “OO” following the “OK”, etc.), or you get an error message instead, please contact us for further assistance.

Updating EDirect

From time to time, NCBI releases new versions of the EDirect software, fixing issues and incorporating new features. New releases are announced in the Release Notes of NCBI’s EDirect documentation.

To update your EDirect installation to the latest version, you can simply re-install EDirect over your existing installation, using the same script you used for the initial installation. See EDirect Installation above.