Skip to content

Clarify ray.shutdown() behavior for local vs remote clusters #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
OneSizeFitsQuorum merged 4 commits into from
Jan 5, 2026
Merged

Clarify ray.shutdown() behavior for local vs remote clusters #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1ea8437
Initial plan
Copilot Jan 5, 2026
52ed366
Clarify ray.shutdown() behavior for local vs remote clusters
Copilot Jan 5, 2026
44e0b31
Clarify that ray.init() auto-detects existing clusters
Copilot Jan 5, 2026
0c05d58
Add note about ray.shutdown() behavior to starting-ray.rst docs
Copilot Jan 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions doc/source/ray-core/starting-ray.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,13 @@ Calling ``ray.init()`` starts a local Ray instance on your laptop/machine. This

When the process calling ``ray.init()`` terminates, the Ray runtime will also terminate. To explicitly stop or restart Ray, use the shutdown API.

.. note::

The behavior of ``ray.shutdown()`` depends on how the cluster was initialized:

* If ``ray.init()`` started a new local cluster, ``ray.shutdown()`` will terminate all the local Ray processes.
* If you connected to an existing cluster (e.g., via ``ray.init(address="auto")`` or ``ray.init(address="ray://<ip>:<port>")``), ``ray.shutdown()`` only disconnects the client -- it does **not** shut down the remote cluster.

.. tab-set::

.. tab-item:: Python
Expand Down
17 changes: 17 additions & 0 deletions python/ray/_private/worker.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2017,6 +2017,23 @@ def shutdown(_exiting_interpreter: bool = False):
need to redefine them. If they were defined in an imported module, then you
will need to reload the module.

.. note::

The behavior of ``ray.shutdown()`` differs depending on how the cluster
was initialized:

* If a new local Ray cluster was started by ``ray.init()`` (i.e., no
``address`` argument was provided and no existing cluster was found,
or ``address="local"`` was explicitly used), ``ray.shutdown()`` will
terminate all the local Ray processes (raylet, object store, etc.)
that were spawned by ``ray.init()``.

* If you connected to an existing cluster (e.g., via
``ray.init(address="auto")`` or ``ray.init(address="ray://<ip>:<port>")``),
``ray.shutdown()`` will only disconnect the client from the cluster.
It will **not** shut down the remote cluster. The cluster will
continue running and can be connected to again.

Args:
_exiting_interpreter: True if this is called by the atexit hook
and false otherwise. If we are exiting the interpreter, we will
Expand Down