Starting Ray¶
This page covers how to start Ray on your single machine or cluster of machines.
Installation¶
Install Ray with pip install -U ray
. For the latest wheels (a snapshot of the master
branch), you can use the instructions at Latest Snapshots (Nightlies).
Note
This step is not required if you are writing a Ray application in Java and you don’t have the need of running your Java application in a multi-node Ray cluster at the development stage. See Local mode for more details.
Build your Java code¶
If your application is written in Java, you need to add Ray dependencies to your project in order to build it.
<dependencies>
<dependency>
<groupId>io.ray</groupId>
<artifactId>ray-api</artifactId>
<version>...</version>
</dependency>
<dependency>
<groupId>io.ray</groupId>
<artifactId>ray-runtime</artifactId>
<version>...</version>
</dependency>
</dependencies>
Note
When you run pip install
to install Ray, Java jars are installed as well. The above dependencies are only used to build your Java code and to run your code in local or single machine mode.
If you want to run your Java code in a multi-node Ray cluster, it’s better to exclude Ray jars when packaging your code to avoid jar conficts if the versions (installed Ray with pip install
and maven dependencies) don’t match.
Starting Ray on a single machine¶
You can start Ray with the init
API (see the code snippet below). It will start the local services that Ray uses to schedule remote tasks and actors and then connect to them. Note that you must initialize Ray before any tasks or actors are called.
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();
...
}
}
To stop or restart Ray, use the shutdown API.
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();
}
}
To check if Ray is initialized, you can call ray.is_initialized()
:
import ray
ray.init()
assert ray.is_initialized() == True
ray.shutdown()
assert ray.is_initialized() == False
To check if Ray is initialized, you can call Ray.isInitialized()
:
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());
}
}
See the Configuration documentation for the various ways to configure Ray.
Using Ray on a cluster¶
There are two steps needed to use Ray in a distributed setting:
You must first start the Ray cluster.
If you have a Ray cluster specification (Using the Ray Cluster Launcher), you can launch a multi-node cluster with Ray initialized on each node with
ray up
. From your local machine/laptop:ray up cluster.yamlTo configure the Ray cluster to run Java code, you need to add the
--code-search-path
option. It’s used to specify classpath for workers in the cluster. Your jar files must be distributed to all the nodes of the Ray cluster before running your code. You also need to make sure the paths of jar files are the same among nodes.You can monitor the Ray cluster status with
ray monitor cluster.yaml
and ssh into the head node withray attach cluster.yaml
.
Specify the address of the Ray cluster when initializing Ray in your code. This causes Ray to connect to the existing cluster instead of starting a new one on the local node.
You need to add the
address
parameter toray.init
(likeray.init(address=...)
). To connect your program to the Ray cluster, add the following to your Python script:ray.init(address="auto")You need to add the
ray.redis.address
parameter to your command line (like-Dray.redis.address=...
).To connect your program to the Ray cluster, run it like this:
java -classpath /path/to/jars/ \ -Dray.redis.address=<address> \ <classname> <args>Note
Specifying
auto
as the Redis address hasn’t been implemented in Java yet. You need to provide the actual Redis address. You can find the address of the Redis server from the output of theray up
command.Your driver code only needs to execute on one machine in the cluster (usually the head node).
Note
Without the address parameter, your Ray program will only be parallelized across a single machine!
Manual cluster setup¶
You can also use the manual cluster setup (Ray with Cluster Managers) by running initialization commands on each node.
On the head node:
# If the ``--redis-port`` argument is omitted, Ray will choose a port at random.
$ ray start --head --redis-port=6379
The command will print out the address of the Redis server that was started (and some other address information).
Then on all of the other nodes, run the following. Make sure to replace <address>
with the value printed by the command on the head node (it should look something like 123.45.67.89:6379
).
$ ray start --address=<address>
If you want to run Java code, you need to specify the classpath via the --code-search-path
option.
$ ray start ... --code-search-path=/path/to/jars
Local mode¶
Caution
This feature is maintained solely to help with debugging, so it’s possible you may encounter some issues. If you do, please file an issue.
By default, Ray will parallelize its workload and run tasks on multiple processes and multiple nodes. However, if you need to debug your Ray program, it may be easier to do everything on a single process. You can force all Ray functions to occur on a single process by enabling local mode as the following:
ray.init(local_mode=True)
java -classpath <classpath> \
-Dray.local-mode=true \
<classname> <args>
Note that some behavior such as setting global process variables may not work as expected.
Note
If you just want to run your Java code in local mode, you can run it without Ray or even Python installed.
What’s next?¶
Check out our Deployment section for more information on deploying Ray in different settings, including Kubernetes, YARN, and SLURM.