Install Ray 2.59.0 for Distributed Computing [Guide]

Ray 2.59.0 on your box by the end of this page: local runtime verified, dashboard up, Docker tags that won’t lie to you. No Fibonacci remote – late-2026 install path only.

Ray is the open-source engine (core runtime plus Data, Train, Tune, Serve) that turns ordinary Python into tasks and actors across cores or machines. Upstream lives at github.com/ray-project/ray; wheels ship from PyPI under Apache 2.0.

System requirements before you touch pip

Match these first or you chase phantom import errors later.

Linux and Apple silicon are first-class per the official installation docs. Treat Windows as single-node experiments only.

Official download source and pip install

Skip random GitHub zipballs. PyPI or pinned rayproject tags only.

# Fresh venv - just do it
python -m venv .venv
source .venv/bin/activate # Windows: .venvScriptsactivate
pip install -U pip

# General apps (core + Dashboard + cluster launcher)
pip install -U "ray[default]==2.59.0"

# ML stack instead (or combine extras)
# pip install -U "ray[data,train,tune,serve]==2.59.0"

# Minimal core only
# pip install -U "ray==2.59.0"

Extras add up: pip install -U "ray[default,train]==2.59.0" is valid. Conda-forge has community packages (ray-default and friends); inside a conda env the docs still prefer pip install ray after the env exists.

First-time configuration: token auth is on by default

The catch is older blog posts never saw this. As of 2.59, token authentication is on by default for local clusters. Call ray.init() with no address and Ray generates or reuses ~/.ray/auth_token, then logs that it did.

Lookup order from the token authentication guide: RAY_AUTH_TOKEN → file at RAY_AUTH_TOKEN_PATH → ~/.ray/auth_token. Opt out on a throwaway laptop with export RAY_AUTH_MODE=disabled before start. Keep the token file permissions tight; don’t commit it.

Minimum local start:

ray start --head --port=6379 --dashboard-host=127.0.0.1
# or let Python own it:
python -c "import ray; ray.init(); print(ray.__version__); ray.shutdown()"

Verify the install works

Three checks. That’s enough.

python -c "import ray; print(ray.__version__)" # expect 2.59.0
ray --help
python - <<'PY'
import ray
ray.init()
print("initialized:", ray.is_initialized())
print("nodes:", ray.nodes())
ray.shutdown()
PY

Used ray start --head? Open http://localhost:8265 (also printed in start logs). ray status should show one alive node. Green light for jobs on this machine.

Docker path (when you want isolation)

Images: rayproject/ray. Pin the version.

# CPU - shm ~30% of host RAM (example: 4g)
docker run --rm -it --shm-size=4g 
 -p 8265:8265 
 rayproject/ray:2.59.0-py311-cpu

# GPU (NVIDIA Container Toolkit)
# docker run --rm -it --gpus all --shm-size=8g rayproject/ray:2.59.0-py311-gpu

Inside: ray start --head --dashboard-host=0.0.0.0, then hit mapped 8265. Object store wants shared memory; without --shm-size Ray falls back to /tmp and yells about it – performance drops hard. Full memory behavior is spelled out in the memory management docs.

Turns out ray-mllatest / latest-gpu stopped moving after 2.30.0. You get a years-old Ray, no error. Build ML deps on rayproject/ray or use runtime envs. And 2.59.0 is the last release publishing CUDA 11.7 (-cu117) images – plan the base upgrade before you bump again.

That pair (frozen ml tags + cu117 sunset) is the kind of landmine you only notice after a worker quietly runs ancient code or dies on a newer GPU.

Common install errors and fixes

Same threads, over and over, on GitHub and discuss.ray.io.

• WARNING: object store is using /tmp instead of /dev/shm – shm too small. Rerun with --shm-size= around 30% of RAM, or cap the store via ray.init(object_store_memory=...) / ray start --object-store-memory=....
• AuthenticationError / “no authentication token was found” – head expects a token you don’t have. Export RAY_AUTH_TOKEN, point RAY_AUTH_TOKEN_PATH at the file, reuse ~/.ray/auth_token, or set RAY_AUTH_MODE=disabled for local-only play.
• No matching distribution found for ray – wrong platform/Python (exotic libc, Python < 3.10, arm container without arm wheels). Use an official manylinux/macOS/Windows wheel or the matching Docker tag.
• Dashboard leftovers after ray stop (Windows beta) – force-kill stray Python processes tied to the Ray session, then clear the session folder under the temp dir.

Logs: /tmp/ray/session_latest/logs (symlink). Start failures → read raylet.err and gcs_server.err first.

Upgrade from an older Ray and clean uninstall

# Upgrade in place
pip install -U "ray[default]==2.59.0"

# Full remove
ray stop --force 2>/dev/null || true
pip uninstall -y ray
# optional: wipe local state
rm -rf ~/.ray /tmp/ray # macOS/Linux; adjust on Windows

Jumping many minor versions? Recreate the venv. Session dirs under /tmp/ray aren’t always purged on hard kills – delete them if disk fills with spilled objects.

FAQ

Which extras should I install for a first laptop deploy?

ray[default]==2.59.0. Add data/train/tune/serve only when you need those libraries.

Do I need Docker to try distributed computing with Ray?

No. venv + pip + ray.init() covers single-machine parallelism. Docker helps when you need reproducible images, GPU passthrough, or a base that matches production KubeRay. Skip --shm-size and the object store falls back to /tmp – you’ll feel it.

I upgraded to 2.59 and scripts that used to connect now fail – what changed?

Local clusters enable token auth by default now. Drivers and CLI tools must see the same token via env, path, or ~/.ray/auth_token. ray.init(address=...) against an authenticated head without it raises AuthenticationError. Share the token, or start with RAY_AUTH_MODE=disabled while you migrate. That’s the whole break; it’s not your network config.

Next: run the three verify commands, open the dashboard once, point a real workload at this local cluster before you touch ray up or KubeRay.