Perforce Public Knowledge Base - Getting Started with Eclipse and P4Eclipse
Perforce Software logo
Reset Search



Getting Started with Eclipse and P4Eclipse

« Go Back



How do I set up Eclipse and Perforce workspaces on Windows, Linux, or Mac OS X operating systems?


P4Eclipse, previously called P4WSAD, is the Eclipse plugin for Perforce.

Prior to downloading P4Eclipse, please check the latest release notes for platform and Eclipse version compatibility. You can find the release notes for the latest P4Eclipse here:

This article is divided into the following sections for your convenience:

Installing Eclipse and P4EclipseP4Eclipse uses its own P4IGNORE rules.  See "Excluding Files from Source Control" in

1. Install Eclipse (if you do not have an existing instance of Eclipse)

  1. Download the latest Eclipse version that is supported by P4Eclipse from:
    http://www.eclipsP4Eclipse uses its own P4IGNORE rules.  See "Excluding Files from Source Control" in

Important: Your Eclipse workspace must be different than your Perforce workspace.

You want the files in your Eclipse projects to be under Perforce control, but you do not want the Eclipse metadata to fall under Perforce control, because it is particular to that installation of Eclipse. Therefore, Eclipse project files must NOT be under the Perforce client root.

Please see KB article #1048: Eclipse vs. Perforce Workspaces for a more detailed explanation.


2. Install the Perforce plug-in

The following instructions apply to Eclipse 3.5/3.6:

Please see the Release Notes for more detailed installation instructions. See the Release Notes for P4WSAD 2009.2 for installation instructions for Websphere Studio and other versions of Eclipse.


3. Configure the Perforce plug-in

Mac Users: Please note that your Preferences window is found under Eclipse | Preferences, rather than the "Window" menu.

  • Uncompress the distribution and install. For example, on Linux, run:
    $ tar -zxvf eclipse-rcp-ganymede-SR1-linux-gtk-x86_64.tar.gz
    $ cd eclipse
    $ ./eclipse
    1. Uninstall any older versions of P4Eclipse/P4WSAD that might have been installed previously. Please see KB article #1049: Uninstalling the P4Eclipse Plug-In for more detailed instructions.

    2. Choose: Help | Install New Software in Eclipse.
    3. In the Available Software dialog, click Add... to add a new site.
    4. In the pop-up dialog, copy and paste the installation URL for the Eclipse release into the Location box:
    5. Check the box for P4Eclipse and then click Next....

      Note: If there is more than one version of Perforce in the list, select the latest one.
    6. Complete the setup by selecting P4Eclipse and clicking Finish. When prompted, restart Eclipse.
After restarting, verify that the Eclipse workspace is not the same as your Perforce workspace, and is not under the control of Perforce. If you are not prompted, choose: File | Switch Workspace | Other

Setting Preferences

General Settings

Descriptions of each of the following settings can be found in Eclipse's Help: 

Help | Help Contents | Perforce SCM | Setting Preferences

As of 2009.1, a pure Java NIO interface (P4Java) is the default method for interacting with the Perforce server.

Open a Perforce perspective by choosing: Window | Open Perspective | Other... | Perforce | OK


P4WSAD 2009.1 and later/P4Eclipse

You will see a "No servers are currently defined..." message under the P4 Connections tab. Create a "New Connection" by clicking on the green 'plus sign' icon.

The "Add a New Perforce Server Connection" form is displayed.

In the Location section, fill in the fields for the "Host", "Port number", and "Charset" (if you have a Unicode server running).  In the Authentication section, fill in the "User", and "Password" fields. Click Next>.

The Choose a Perforce Client Workspace form is displayed.

Either choose an existing client workspace for your user ID from the list box, or create a new client workspace by entering the name of the client in the Workspace name field and the client root in the Location field. Click Finish>.

The P4 Connections pane shows a list of depots available to you in your Perforce server.


P4WSAD 2008.2

You will see a "No servers are currently defined..." message under the P4 Depots tab. Create a "New Connection" by clicking on the green 'plus sign' icon, and filling in the values for the "Port", "User", and "Client Workspace" (and "Charset" if you have a Unicode server running).

Note: You cannot create a Perforce client workspace with the P4Eclipse, so the client must already exist. Run p4 info from within your client workspace to get the correct P4PORT, P4USER, and P4CLIENT settings.

If you get an error message stating:

P4 command line application not found

You'll need to tell Eclipse where the P4 command-line executable is located. To do this, choose: Window | Preferences | Team (click arrow) | Perforce, and click on the radio button for the "Location:" field under the "Location of p4 executable" section. Specify the path to P4 (or p4.exe executable).

You can now import existing Eclipse projects by selecting "Projects from Perforce" from the File | Import menu or submitting an existing project to Perforce by right-clicking an Eclipse project, choosing Team | Share Project and then selecting Perforce.

Enabling Label Decorations

As of 2009.1 the decorations are configured by default, and are consistent with P4V.

  1. Choose: Window | Preferences | General | Appearance | Label Decorations
  2. Check the "Perforce" box, and click Apply.
  3. Choose: Window | Preferences | Team | Perforce | Label Decorations
  4. Check the box under Ignored Resource Decoration Text labeled "Decorate files/folders contained in .p4ignore".
  5. Choose appropriate locations for File Decoration Icons such as Bottom Right, Top Left, Top Left, Top Right, Top Right, Bottom Left. Click the "OK" button to accept the changes.

Ignoring Files to Add

P4Eclipse uses its own P4IGNORE rules.  See "Excluding Files from Source Control" in


Customize Perspectives

To customize perspectives, choose: Window | Customize Perspective | Command Groups Availability tab | check Perforce | OK

Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255