Configuring Ray

Tune cluster, runtime, and node-level configuration for Ray Core.

Ray exposes configuration through ray.init parameters, environment variables, and command-line flags to ray start.

Initialize the runtime

ray.init(
    address="auto",
    namespace="my_app",
    runtime_env={"pip": ["numpy"]},
    logging_level="INFO",
)

Parameter	What it does
address	Connect to an existing cluster. Use "auto" for the local Ray service or a head-node address.
namespace	Logical grouping for named actors.
runtime_env	Default runtime environment for the job.
num_cpus, num_gpus	Cap resources used by the local Ray instance.
object_store_memory	Object store size in bytes.
_temp_dir	Where to write logs, sockets, and spilled objects.

Start a head node

ray start --head \
  --port=6379 \
  --num-cpus=8 \
  --num-gpus=1 \
  --resources='{"high_memory": 4}' \
  --temp-dir=/tmp/ray

Start a worker node

ray start --address=<head_ip>:6379 --num-cpus=8

Environment variables

Variable	Effect
RAY_ADDRESS	Default address for ray.init().
RAY_RUNTIME_ENV_TIMEOUT_SECONDS	Maximum time to install runtime env.
RAY_DEDUP_LOGS	Deduplicate identical log lines from many workers.
RAY_TMPDIR	Override the temp directory.
RAY_BACKEND_LOG_LEVEL	Log level for Ray’s C++ core.

Object store configuration

ray.init(
    object_store_memory=4 * 1024**3,
    _system_config={
        "automatic_object_spilling_enabled": True,
        "object_spilling_config": '{"type":"filesystem","params":{"directory_path":"/mnt/spill"}}',
    },
)

Logging

Ray writes per-worker logs into /tmp/ray/session_*/logs. To control log level:

ray.init(logging_level="DEBUG")

Configure log rotation with RAY_ROTATION_MAX_BYTES and RAY_ROTATION_BACKUP_COUNT.

Resource labels

Custom resources let you pin tasks and actors to specific node classes.

ray start --head --resources='{"high_memory": 8, "tpu": 1}'

@ray.remote(resources={"high_memory": 1})
def heavy(): ...

Next steps

Scheduling

Resource requests, placement groups, and locality.

Troubleshooting

Diagnosing common Ray issues.