Step 1: choose your products


Step 2: choose an Aqua version

Please select one of the Aqua versions shown below. How do I decide?

Aqua release train version

IBM Explorer for z/OS Aqua (or simply Aqua) is a continuous delivery release train platform that brings together a set of Eclipse-based mainframe development tools and offerings in order to provide z/OS application developers and system programmers an easy way to install, deploy and maintain our IBM Eclipse-based products.

What is the difference between the versions of Aqua?

Each version of Aqua is based on a different version of Eclipse. New features and products will be integrated with newer versions of Aqua while the previous versions will remain in support mode moving forward.

Can I upgrade an Aqua environment directly to another version?

It is not possible to install plug-ins and tools onto an Aqua environment that is from a different Aqua version since each version is based on a specific Eclipse iteration. To move from one Aqua version to another (eg. Aqua 3.1 to Aqua 3.2), you will need a fresh environment and from there you can bring over the workspace data.

Aqua 3.3

(Eclipse V4.23)

This option is unavailable because one or more products that have been selected are not available for this version of Aqua.

A workaround is required to install IBM Z Open Development and IBM Rational Team Concert together. Please see this blog post for more details.

Aqua 3.2

(Eclipse Photon V4.8)

This option is unavailable because one or more products that have been selected are not available for this version of Aqua.

A workaround is required to install IBM Z Open Development and IBM Rational Team Concert together. Please see this blog post for more details.

Step 3: choose an installation client

Please select one of the installation methods shown below. How do I decide?

Aqua tools packaging formats

The IBM Aqua products can be installed using two different packaging formats: IBM Installation Manager or Eclipse p2.

IBM Installation Manager (IM)

IBM Installation Manager is IBM’s solution for managing Eclipse-based tools such as Aqua tools. You install a separate utility (IBM Installation Manager) that keeps track of your installed Eclipse-based tools and is able to modify and extend those tools. Some Aqua tools must be installed using IBM Installation Manager — they are not available via Eclipse p2.

Eclipse p2

Eclipse p2 is an installation technology built into Eclipse tools. It can be accessed using the built-in ‘Install New Software’ option. It can often be the quickest way to get going, though not all Aqua tools are available via Eclipse p2.

Making a choice

When choosing the packaging format, ask these questions:

  • Are all the tools I want to install together supported by this packaging format? Also consider tools you may want to install in the same Eclipse in future. Once you start to create an Eclipse with one of these methods, it’s important to continue to use the same method if you extend it. This avoids the package managers getting confused, resulting in errors. You can see which packaging formats support which tools in the table of all tools.
  • Do you have an existing enterprise deployment tool that you will use for rollout? Does it already have a way of supporting IBM Installation Manager or Eclipse p2?
  • Do you just want to try out a tool quickly? Using Eclipse p2 will get you going faster.

IBM Installation Manager

Install with IBM Installation Manager, an application that can access the software repository and guide you through each step of the process.

  • For IDz 14.1.x using Installation Manager and Aqua 3.1:
    • To update - uncheck the Show recommended only option in order to be able to select the latest version of 14.1.x
    • To install - check the Show all versions option in order to be able to select the latest version of 14.1.x
Please note IBM Installation Manager V1.9.2.3 or higher is required.

Eclipse p2

Install with the Eclipse p2 provisioning platform, a technology for managing Eclipse- and Equinox-based applications and plug-ins.

Please note the following products and their specific version restriction when installing them with Eclipse p2 for Aqua 3.1:
  • IBM Developer for z/OS - V14.2.x only
  • IBM Debug for z/OS - V14.2.x only

Step 4: choose your starting point

Starting from fresh

I do not have IBM Installation Manager installed on my machine.

Extending an existing Installation Manager instance

I have IBM Installation Manager installed on my machine.

Hosting an internal Installation Manager repository

I want to download the entire IBM Installation Manager repository to host internally to my organisation.

This option is unavailable for Aqua 3.0.

Starting from fresh

I do not have Eclipse installed on my machine.

Extending an existing Eclipse instance

I want to extend an existing instance of Eclipse I have installed on my machine.

Hosting an internal repository

I want to download the entire p2 repository to host internally to my organisation.

Download and install

These instructions will show you how to install the selected products, using IBM Installation Manager, from an online IBM repository.

Download and install IBM Installation Manager

If you already have IBM Installation Manager installed, skip this step.

3.0
Aqua 3.0 (Eclipse Luna V4.4)
3.1
Aqua 3.1 (Eclipse Neon V4.6)
3.2
Aqua 3.2 (Eclipse Photon V4.8)
3.3
Aqua 3.3 (Eclipse V4.23)
LINUX
Linux
WINDOWS
Windows
MAC
MacOS
Change...
  1. Download, unzip, and install IBM Installation Manager (IM) using one of the following options:
    • Prerequisite: clear the extended attributes of IM zip file:
      xattr -c path_to_IM_zip
    • User install: InstallerImage_macosx_cocoa_x86_64/UserInst.app
    • Admin install: InstallerImage_macosx_cocoa_x86_64/Install.app or imLauncherMac.sh
    • Installation Manager may require root access to install - you can also start the installer by using the sudo command below:
      sudo Downloads/IM_extractdir/Install.app/Contents/MacOS/install
      IM_extractdir is the directory that the package was extracted to
    • User install: imLauncherWindowsUser.bat
    • Admin install: imLauncherWindows.bat
    • User install: imLauncherLinuxUser.sh
    • Admin install: imLauncherLinux.sh
  2. Restart IM after the installation has completed.

Install product offerings through IM

  1. In IBM Installation Manager, select 'Install' to view and select product offerings for installation.

    Choosing packages to install. The version numbers may differ from what you see.

  2. Select to install the following products:
    • Review and complete the remaining pages in IBM Installation Manager.

    These instructions will show you how to extend an existing Eclipse instance with the selected products, using IBM Installation Manager, from an online IBM repository.

    Adding a new online repository to IM

    If you do not need to add a new online repository to IBM Installation Manager, skip this step.

    1. Update IBM Installation Manager to version 1.9.1.4 or later.
    2. Update IBM Installation Manager to version 1.9.1.4 or later.
    3. Update IBM Installation Manager to version 1.8.5.1 or later.
    4. Launch IBM Installation Manager.
    5. In the menu bar, select 'File' -> 'Preferences...', select the 'Repositories' tab, and select 'Add Repository'.
    6. In the menu bar, select 'IBM Installation Manager' -> 'Preferences...', select the 'Repositories' tab, and select 'Add Repository'.
    7. In the menu bar, select 'File' -> 'Preferences...', select the 'Repositories' tab, and select 'Add Repository'.
    8. Select the 'Add Repository...' button and paste the following repository URL:
      • z/OS Explorer Aqua V3.0 (Eclipse Luna V4.4) https://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua/
      • z/OS Explorer Aqua V3.1 (Eclipse Neon V4.6) https://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua3.1/
      • z/OS Explorer Aqua V3.2 (Eclipse Photon V4.8) https://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua3.2/
      • z/OS Explorer Aqua V3.3 (Eclipse V4.23) https://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua3.3/
    9. Select 'OK' to confirm the new repository.

    Rational Developer for z Systems (RDz)
    Users of RDz V9.1 and below must uninstall RDz and create a fresh installation of IDz in order to upgrade. Users of RDz V9.5.x are unaffected by this limitation. More details

    Extending an existing IM installation

    1. In Installation Manager, click Install to view and select product offering(s) for installation.
    2. Select the following products:
      • Review and accept the licenses.
      • In the next step, select the "Use the existing package group" radial button.
      • Continue to follow the instructions to select translations and additional features, then complete the installation.

      These instructions will show you how to use a locally hosted repository to install products using IBM Installation Manager.

      Download and install IBM Installation Manager

      If you already have Installation Manager installed, skip this step.

      3.0
      Aqua 3.0 (Eclipse Luna V4.4)
      3.1
      Aqua 3.1 (Eclipse Neon V4.6)
      3.2
      Aqua 3.2 (Eclipse Photon V4.8)
      3.3
      Aqua 3.3 (Eclipse V4.23)
      LINUX
      Linux
      WINDOWS
      Windows
      MAC
      MacOS
      Change...
      1. Download, unzip, and install IBM Installation Manager (IM) using one of the following options:
        • Prerequisite: clear the extended attributes of IM zip file:
          xattr -c path_to_IM_zip
        • User install: InstallerImage_macosx_cocoa_x86_64/UserInst.app
        • Admin install: InstallerImage_macosx_cocoa_x86_64/Install.app or imLauncherMac.sh
        • Installation Manager may require root access to install - you can also start the installer by using the sudo command below:
          sudo Downloads/IM_extractdir/Install.app/Contents/MacOS/install
          IM_extractdir is the directory that the package was extracted to
        • User install: imLauncherWindowsUser.bat
        • Admin install: imLauncherWindows.bat
        • User install: imLauncherLinuxUser.sh
        • Admin install: imLauncherLinux.sh
      2. Restart IM after the installation has completed.

      Use pre-packaged repository zip files to prepare a local repository

      1. Refer to the table below and download the repository zip files for each of your selected products:
        • [1] Downloading will be available soon, see notes

        Products labeled required are necessary for the successful installation of the other products selected.

      2. In the offline environment, extract the archive(s) into a local directory of your choosing.

      Use pre-packaged repository zip files to prepare a local repository

      1. Download the following zip file which includes all offerings pre-packaged for use with IBM Installation Manager.
        Alternatively, refer to the table below and download the repository zip files for each of your selected products:

        Products labeled required are necessary for the successful installation of the other products selected.

      2. In the offline environment, extract the archive(s) into a local directory of your choosing.

      Use pre-packaged repository zip files to prepare a local repository

      1. Download the following zip file which includes all offerings pre-packaged for use with IBM Installation Manager.
        Alternatively, refer to the table below and download the repository zip files for each of your selected products:

        Products labeled required are necessary for the successful installation of the other products selected.

      2. In the offline environment, extract the archive(s) into a local directory of your choosing.

      Add an offline repository to IM

      1. Launch IBM Installation Manager.
      2. In the menu bar, select 'File' -> 'Preferences...', select the 'Repositories' tab, and select 'Add Repository'.
      3. In the menu bar, select 'IBM Installation Manager' -> 'Preferences...', select the 'Repositories' tab, and select 'Add Repository'.
      4. In the menu bar, select 'File' -> 'Preferences...', select the 'Repositories' tab, and select 'Add Repository'.
      5. Select the 'Add Repository...' button and supply the location of your locally unzipped repository.
      6. Select 'OK' to confirm the new repository.

      Install product offerings through IM

      1. In IBM Installation Manager, select 'Install' to view and select product offerings for installation.

        Choosing packages to install. The version numbers may differ from what you see.

      2. Select to install the following products:
        • Review and complete the remaining pages in IBM Installation Manager.

        These instructions will show you how to install a new instance of Eclipse with the selected products, using Eclipse p2, from an online IBM repository.

        Downloading and extracting the platform executable

        3.0
        Aqua 3.0 (Eclipse Luna V4.4)
        3.1
        Aqua 3.1 (Eclipse Neon V4.6)
        3.2
        Aqua 3.2 (Eclipse Photon V4.8)
        3.3
        Aqua 3.3 (Eclipse V4.23)
        LINUX
        Linux
        WINDOWS
        Windows
        MAC
        MacOS
        Change...
        IBM Developer for z/OS (V14.2) 32-bit 64-bit
        IBM Developer for z/OS (V14.2) 32-bit 64-bit
        IBM Developer for z/OS (V14.2) Download 64-bit
        IBM Z Open Development 32-bit 64-bit
        IBM Z Open Development 32-bit 64-bit
        IBM Z Open Development Download 64-bit
        IBM Developer for z/OS (V15.0) 32-bit 64-bit
        IBM Developer for z/OS (V15.0) 32-bit 64-bit
        IBM Developer for z/OS (V15.0) Download 64-bit
        IBM Developer for z/OS (V16.0) Download 64-bit
        IBM Developer for z/OS (V16.0) Download 64-bit
        IBM Developer for z/OS (V16.0) Available soon
        1. Download and extract the package to a location of your choosing.
          • MacOS only: prerequisite to upzipping, clear the extended attributes of the zip file:
            xattr -c path_to_zip

          • MacOS only: after extracting the client file contents, it is recommended to move the application to the "Applications" folder so that it is possible to update to a new release - updates are not possible when the client files are placed in a different folder.
        2. Launch the platform application by running "zosexplorer". Launch the platform application by running "zosexplorer.exe". Launch the platform application by running "Zosexplorer.app". Why is the executable from z/OS Explorer?
        3. Launch the platform application by running "Z_Open_Development". Launch the platform application by running "Z_Open_Development.exe". Launch the platform application by running "Z_Open_Development.app".
        4. Launch the platform application by running "zosexplorer". Launch the platform application by running "zosexplorer.exe". Launch the platform application by running "Zosexplorer.app". Why is the executable from z/OS Explorer?

        Install additional products

        1. Important: IBM Z Open Unit Test is currently only supported on Windows. The following steps are not applicable if the operating system is MacOS or Linux.
        2. Important: a workaround is required to install IBM Z Open Development and IBM Rational Team Concert together. Please see this blog post .
        3. In the menu bar, select 'Help' -> 'Install New Software...'.
        4. Select to work with the "IBM Explorer for z/OS Update Site" and allow the list of available software to load.
        5. Select additional products from the list.
        6. Select the following products from the list:
          • Review and complete the remaining steps in the install wizard.

          These instructions will show you how to extend an existing instance of Eclipse with the selected products, using Eclipse p2, from an online IBM repository.

          Adding a new online repository to p2

          1. Launch Eclipse. (Note: IBM Developer for z/OS V16.0.x does not support direct installation on top of an official Eclipse instance.)
          2. In the menu bar, select 'Help' -> 'Install New Software...'.
          3. In the install dialog, select "Add...".
          4. In the "Add Repository" dialog add the repository URL:
            • z/OS Explorer Aqua V3.0 (Eclipse Luna V4.4) https://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua/
            • z/OS Explorer Aqua V3.1 (Eclipse Neon V4.6) https://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua3.1/
            • z/OS Explorer Aqua V3.2 (Eclipse Photon V4.8) https://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua3.2/
            • z/OS Explorer Aqua V3.3 (Eclipse V4.23) https://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua3.3/
          5. At the bottom of the window, enable the checkbox 'Group items by category' to view the list of all individual products.
          6. Important: a workaround is required to install IBM Z Open Development and IBM Rational Team Concert together. Please see this blog post .
          7. Select additional products from the list.
          8. Important: IBM Z Open Unit Test is currently only supported on Windows. The following steps are not applicable if the operating system is MacOS or Linux.
          9. Install the following products:
            • Review and complete the remaining steps in the install wizard.
            If you experience any problem with RSE (Remote System Explorer), please refer to this section:
            • To resolve the error, check "Show original error and build my own solution" and "Remove items already installed" when the Install Remediation panel is presented
            • See this page for more in-depth information.

            These instructions will show you how to use a locally hosted repository to install products using Eclipse p2.

            Downloading and installing Eclipse

            If you or your users already have an instance of Eclipse installed, skip this step.

            1. Download an instance of Eclipse from the Aqua repository.


              MacOS only: prerequisite to upzipping, clear the extended attributes of the zip file:
              xattr -c path_to_zip

              3.0
              Aqua 3.0 (Eclipse Luna V4.4)
              3.1
              Aqua 3.1 (Eclipse Neon V4.6)
              3.2
              Aqua 3.2 (Eclipse Photon V4.8)
              3.3
              Aqua 3.3 (Eclipse V4.23)
              LINUX
              Linux
              WINDOWS
              Windows
              MAC
              MacOS
              Change...
              IBM Developer for z/OS (V14.2) 32-bit 64-bit
              IBM Developer for z/OS (V14.2) 32-bit 64-bit
              IBM Developer for z/OS (V14.2) Download 64-bit
              IBM Z Open Development 32-bit 64-bit
              IBM Z Open Development 32-bit 64-bit
              IBM Z Open Development Download 64-bit
              IBM Developer for z/OS (V15.0) 32-bit 64-bit
              IBM Developer for z/OS (V15.0) 32-bit 64-bit
              IBM Developer for z/OS (V15.0) 64-bit
              IBM Developer for z/OS (V16.0) Download 64-bit
              IBM Developer for z/OS (V16.0) Download 64-bit
              IBM Developer for z/OS (V16.0) Available soon
              • Alternatively, download an instance of Eclipse directly from the official site. (Note: IBM Developer for z/OS V16.0.x does not support direct installation on top of an official Eclipse instance.)

            Download the entire p2 repository or individual zip files to host internally

            1. Download the necessary files for hosting the p2 repository from one of the options below:
              • Entire p2 repository
                3.0
                Aqua update site package
                p2
                Eclipse Luna V4.4
                3.1
                Aqua update site package
                p2
                Eclipse Neon V4.6
                3.2
                Aqua update site package
                p2
                Eclipse Photon V4.8
                3.3
                Aqua update site package
                p2
                Eclipse V4.23
              • Individual p2 zip files
              • Individual p2 zip files
              • Individual p2 zip files
            2. Host the package(s) in a location of your choosing.

            Point Eclipse at the locally hosted repository

            1. Important: a workaround is required to install IBM Z Open Development and IBM Rational Team Concert together. Please see this blog post .
            2. Launch Eclipse.
            3. In the menu bar, select 'Help' -> 'Install New Software...'.
            4. In the install dialog, select "Add...".
            5. In the "Add Repository" dialog, select "Archive" and specify the location of your offline installation package.
            6. Select additional products from the list.
            7. Important: IBM Z Open Unit Test is currently only supported on Windows. The following steps are not applicable if the operating system is MacOS or Linux.
            8. Install the following products: