Starting Ray#

This page describes how to start Ray on a single machine or on a cluster of machines.

Tip

Install Ray before you follow the instructions on this page.

What’s the Ray runtime?#

Ray programs parallelize and distribute work through an underlying Ray runtime. The Ray runtime consists of multiple services and processes that run in the background and handle communication, data transfer, scheduling, and more. You can start the Ray runtime on a laptop, a single server, or multiple servers.

You can start the Ray runtime in three ways:

In all cases, ray.init() tries to automatically find a Ray instance to connect to. It checks the following, in order:

  1. The concrete address that you pass to ray.init(address=<address>).

  2. If you don’t pass an address, or pass "auto", the RAY_ADDRESS OS environment variable.

  3. If RAY_ADDRESS isn’t set, the latest Ray instance that ray start started on the same machine.

Starting Ray on a single machine#

Calling ray.init() starts a local Ray instance on your laptop or machine. This machine becomes the head node.

Note

As of Ray 1.5, Ray calls ray.init() automatically the first time you use a Ray remote API.

import ray
# Other Ray APIs will not work until `ray.init()` is called.
ray.init()

import io.ray.api.Ray;

public class MyRayApp {

  public static void main(String[] args) {
    // Other Ray APIs will not work until `Ray.init()` is called.
    Ray.init();
    ...
  }
}

#include <ray/api.h>
// Other Ray APIs will not work until `ray::Init()` is called.
ray::Init()

When the process that calls ray.init() exits, the Ray runtime also stops. To stop or restart Ray explicitly, use the shutdown API.

Note

The behavior of ray.shutdown() depends on whether ray.init() started a new cluster or connected to an existing one:

  • If ray.init() started a new local cluster, ray.shutdown() stops all the local Ray processes.

  • If you connected to an existing cluster, for example with ray.init(address="auto") or ray.init(address="ray://<ip>:<port>"), ray.shutdown() only disconnects the client. It doesn’t shut down the remote cluster.

import ray
ray.init()
... # ray program
ray.shutdown()

import io.ray.api.Ray;

public class MyRayApp {

  public static void main(String[] args) {
    Ray.init();
    ... // ray program
    Ray.shutdown();
  }
}

#include <ray/api.h>
ray::Init()
... // ray program
ray::Shutdown()

To check whether Ray is initialized, use the is_initialized API.

import ray
ray.init()
assert ray.is_initialized()

ray.shutdown()
assert not ray.is_initialized()

import io.ray.api.Ray;

public class MyRayApp {

public static void main(String[] args) {
        Ray.init();
        Assert.assertTrue(Ray.isInitialized());
        Ray.shutdown();
        Assert.assertFalse(Ray.isInitialized());
    }
}

#include <ray/api.h>

int main(int argc, char **argv) {
    ray::Init();
    assert(ray::IsInitialized());

    ray::Shutdown();
    assert(!ray::IsInitialized());
}

For the ways to configure Ray, see the Configuration documentation.

Starting Ray through the CLI (ray start)#

Run ray start from the CLI to start a single-node Ray runtime on a machine. This machine becomes the head node.

$ ray start --head --port=6379

Local node IP: 192.123.1.123
2020-09-20 10:38:54,193 INFO services.py:1166 -- View the Ray dashboard at http://localhost:8265

--------------------
Ray runtime started.
--------------------

...

To connect to this Ray instance, start a driver process on the same node where you ran ray start. ray.init() automatically connects to the latest Ray instance.

import ray
ray.init()

import io.ray.api.Ray;

public class MyRayApp {

  public static void main(String[] args) {
    Ray.init();
    ...
  }
}

java -classpath <classpath> \
  -Dray.address=<address> \
  <classname> <args>

#include <ray/api.h>

int main(int argc, char **argv) {
  ray::Init();
  ...
}

RAY_ADDRESS=<address> ./<binary> <args>

To create a Ray cluster, connect other nodes to the head node by calling ray start on those nodes as well. For more details, see Launching an On-Premise Cluster. Calling ray.init() on any machine in the cluster connects to the same Ray cluster.

Launching a Ray cluster (ray up)#

You can launch Ray clusters with the cluster launcher. The ray up command uses the Ray cluster launcher to start a cluster on the cloud, which creates a designated head node and worker nodes. ray up calls ray start to create the Ray cluster.

Your code needs to run on only one machine in the cluster, usually the head node.

To connect to the Ray cluster, call ray.init from one of the machines in the cluster. ray.init connects to the latest Ray cluster:

ray.init()

The machine that calls ray up isn’t part of the Ray cluster, so calling ray.init on that machine doesn’t attach to the cluster.

What’s next?#

To deploy Ray in different settings, including Kubernetes, YARN, and SLURM, see the deployment section.