Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 API for Ruby Documentation | 2025.2

# Installing P4 API for Ruby

There are several ways to install P4 API for Ruby:

- Install P4 API for Ruby using gem
- Install P4 API for Ruby on macOS or Linux
- Install P4 API for Ruby from source

In each case, ensure you have met all the criteria of the prerequisites

## Prerequisites

- Ensure your machine meets the system requirements. For information, see System Requirements and Release Notes.

- The latest version of P4 API for Ruby requires Ruby 3.2 and above. To check which version of Ruby you have, run the following command:

  `ruby -v`

## Install P4 API for Ruby using gem

The easiest way to install P4 API for Ruby is to use gem.

The installation package gem is included with Ruby. To check if gem is installed, run `gem --version`.

To install P4 API for Ruby using gem, follow these steps:

1. Open a terminal or command prompt.

2. (Optional) Upgrade gem using the following command:

   `gem update --system`

3. Install P4 API for Ruby using the following command:

   `gem install p4ruby`

4. If P4 API for Ruby is installed correctly, you will see the following output in the terminal or command prompt:

   `Successfully installed p4ruby-<VERSION>`

   Where `<VERSION>` is the installed version of P4 API for Ruby.

## Install P4 API for Ruby on macOS or Linux

If you are installing P4 API for Ruby on macOS or Linux, the P4 API for Ruby gem must be compiled locally against your Ruby installation. If you can build the core Ruby distribution locally, you should be able to install P4 API for Ruby without issues.

This method requires P4 API for C/C++. Download P4 API for C/C++ from the Perforce website and make a note of its location.

The P4 API for C/C++ version must match the major and minor version of the P4 API for Ruby gem.

If you are manually specifying the P4 API for C/C++ location using `--with-p4api-dir`, ensure the headers and libraries are compatible with your Ruby version and platform.

The preferred installation method uses Bundler.

1. If you do not have Bundler, download it from the Bundler website.

2. Using Bundler, run the following:

   `gem 'p4ruby', '~> 2020.1'`

3. Then run:

   `bundle install --with-p4api-dir=<DIR>`

   Where, `<DIR>` is path to your local P4 API for C/C++ installation.

## Install P4 API for Ruby from source

The official version of P4 API for Ruby exists as source on GitHub.

Instructions for building are in the `BUILD.md` file, which is also hosted on GitHub.

## Sample script to test P4 API for Ruby

To further check if P4 API for Ruby has been installed correctly, create a simple script that connects to your server.

Create `test_p4.rb` in a folder (for example, `C:\p4ruby`) with the following code:

Copy

    require 'P4'

    p4 = P4.new
    p4.user   = 'user.name'     # enter your username
    p4.client = 'work_space'    # enter your workspace
    p4.port   = 'perforce:1666' # enter your hostname

    p4.connect
    puts p4.run('info')  # prints Perforce server info
    p4.disconnect

To run the script:

1. Open Command Prompt and navigate to your script folder:

   `cd c:\p4ruby`

2. Run the following:

   `ruby test_p4.rb`

3. If P4 API for Ruby successfully connects, server information will be output to the terminal.

Your search for returned results