Forking an open source repository is a best practice when looking to contribute, as it allows you to make and test changes without affecting the original project, ensuring a clean and organized collaboration process.
You can propose changes to the main project by submitting a pull request to the main project's repository.

1. Navigate to the `Ray GitHub repository <https://github.com/ray-project/ray>`_.
2. Follow these `GitHub instructions <https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_, and do the following:

    a. `Fork the repo <https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository>`_ using your preferred method.
    b. `Clone <https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository>`_ to your local machine.
    c. `Connect your repo <https://docs.github.com/en/get-started/quickstart/fork-a-repo#configuring-git-to-sync-your-fork-with-the-upstream-repository>`_ to the upstream (main project) Ray repo to sync changes.


.. _prepare-venv:

Prepare a Python virtual environment

.. tab-item:: conda

    Set up a ``conda`` environment named ``myenv``:

    .. code-block:: shell

        conda create -c conda-forge python=3.10 -n myenv


    Activate your virtual environment to tell the shell/terminal to use this particular Python:

    .. code-block:: shell

        conda activate myenv

    You need to activate the virtual environment every time you start a new shell/terminal to work on Ray.

.. tab-item:: venv

    Use Python's integrated ``venv`` module to create a virtual environment called ``myenv`` in the current directory:

    .. code-block:: shell

        python -m venv myenv

    This contains a directory with all the packages used by the local Python of your project. You only need to do this step once.

    Activate your virtual environment to tell the shell/terminal to use this particular Python:

    .. code-block:: shell

        source myenv/bin/activate

    You need to activate the virtual environment every time you start a new shell/terminal to work on Ray.

    Creating a new virtual environment can come with older versions of ``pip`` and ``wheel``. To avoid problems when you install packages, use the module ``pip`` to install the latest version of ``pip`` (itself) and ``wheel``:

    .. code-block:: shell

        python -m pip install --upgrade pip wheel

# For example, for Python 3.10:
pip install -U https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-3.0.0.dev0-cp310-cp310-manylinux2014_x86_64.whl

# This replaces `<package path>/site-packages/ray/<package>`
# with your local `ray/python/ray/<package>`.
python python/ray/setup-dev.py

# This links all folders except "_private" and "dashboard" without user prompt.
python python/ray/setup-dev.py -y --skip _private dashboard

# To uninstall, delete the symlinks first.
rm -rf <package path>/site-packages/ray # Path will be in the output of `setup-dev.py`.
pip uninstall ray # or `pip install -U <wheel>`

.. tip:: If you're only editing Tune/RLlib/Autoscaler files, follow :ref:`python-develop` instead to avoid long build times.

To build Ray on Ubuntu, run the following commands:

.. code-block:: bash

  sudo apt-get update
  sudo apt-get install -y build-essential curl clang-12 pkg-config psmisc unzip

  # Install Bazelisk.
  ci/env/install-bazel.sh

  # Install node version manager and node 14
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
  nvm install 14
  nvm use 14

The ``install-bazel.sh`` script installs ``bazelisk``. Note that ``bazel`` is installed at ``$HOME/bin/bazel``; make sure it's on your ``PATH``. If you prefer to use ``bazel`` directly, only version ``6.5.0`` is currently supported.

For RHELv8 (Redhat EL 8.0-64 Minimal), run the following commands:

.. code-block:: bash

  sudo yum groupinstall 'Development Tools'
  sudo yum install psmisc

In RedHat, install Bazel manually from this link: https://bazel.build/versions/6.5.0/install/redhat

Preparing to build Ray on macOS

Make sure you have a local clone of Ray's git repository (see :ref:`fork-ray-repo`). You also need to install NodeJS_ to build the dashboard.

Enter into the project directory, for example:

.. code-block:: shell

  cd ray

Build the dashboard. From inside your local Ray project directory, enter the dashboard client directory:

.. code-block:: bash

  cd python/ray/dashboard/client

Install the dependencies and build the dashboard:

.. code-block:: bash

  npm ci
  npm run build

Move back to the top-level Ray directory:

.. code-block:: shell

  cd -


Now let's build Ray for Python. Make sure you activate any Python virtual (or conda) environment (see :ref:`prepare-venv`).

Enter into the ``python/`` directory inside of the Ray project directory and install the project with ``pip``:

.. code-block:: bash

  # Install Ray.
  cd python/
  # Install required dependencies.
  pip install -r requirements.txt
  # You may need to set the following two env vars if you have a macOS ARM64(M1) platform.
  # See https://github.com/grpc/grpc/issues/25082 for more details.
  # export GRPC_PYTHON_BUILD_SYSTEM_OPENSSL=1
  # export GRPC_PYTHON_BUILD_SYSTEM_ZLIB=1
  pip install -e . --verbose  # Add --user if you see a permission denied error.

The ``-e`` means "editable", so changes you make to files in the Ray
directory take effect without reinstalling the package.

.. warning:: Don't run ``python setup.py install`` — Python copies files from the Ray directory to a packages directory (``/lib/python3.6/site-packages/ray``), so changes you make to files in the Ray directory won't have any effect.

If your machine runs out of memory during the build, add the following to ``~/.bazelrc``:

  .. code-block:: shell

    build --local_ram_resources=HOST_RAM*.5 --local_cpu_resources=4

  The ``build --disk_cache=~/bazel-cache`` option can also speed up repeated builds.

If you run into an error building protobuf, switching from miniforge to anaconda might help.

.. _NodeJS: https://nodejs.org

Building Ray on Windows (full)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Requirements**

The following links were accurate at the time of writing. If a URL has changed, search the organization's site.

- Bazel 6.5.0 (https://github.com/bazelbuild/bazel/releases/tag/6.5.0)
- Microsoft Visual Studio 2019 (or Microsoft Build Tools 2019 - https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019)
- JDK 15 (https://www.oracle.com/java/technologies/javase-jdk15-downloads.html)
- Miniforge 3 (https://github.com/conda-forge/miniforge/blob/main/README.md)
- git for Windows, version 2.31.1 or later (https://git-scm.com/download/win)

You can also use the included script to install Bazel:

.. code-block:: bash

  # Install Bazel.
  ray/ci/env/install-bazel.sh
  # (Windows users: please manually place Bazel in your PATH, and point
  # BAZEL_SH to MSYS2's Bash: ``set BAZEL_SH=C:\Program Files\Git\bin\bash.exe``)

**Steps**

1. Enable Developer mode on Windows 10 systems. This is necessary so git can create symlinks.

   1. Open Settings app;
   2. Go to "Update & Security";
   3. Go to "For Developers" on the left pane;
   4. Turn on "Developer mode".

2. Add the following Miniforge subdirectories to PATH. If Miniforge was installed for all users, the following paths are correct. If Miniforge is installed for a single user, adjust the paths accordingly.

   - ``C:\ProgramData\miniforge3``
   - ``C:\ProgramData\miniforge3\Scripts``
   - ``C:\ProgramData\miniforge3\Library\bin``

3. Define an environment variable ``BAZEL_SH`` to point to ``bash.exe``. If git for Windows was installed for all users, bash's path should be ``C:\Program Files\Git\bin\bash.exe``. If git was installed for a single user, adjust the path accordingly.

4. Install Bazel 6.5.0. Go to the Bazel 6.5.0 release page and download
``bazel-6.5.0-windows-x86_64.exe``. Copy the exe into the directory of your choice.
Define an environment variable ``BAZEL_PATH`` to the full exe path (example:
``set BAZEL_PATH=C:\bazel\bazel.exe``). Also add the Bazel directory to
``PATH`` (example: ``set PATH=%PATH%;C:\bazel``)

5. Download ray source code and build it.

.. code-block:: shell

  # cd to the directory under which the ray source tree will be downloaded.
  git clone -c core.symlinks=true https://github.com/ray-project/ray.git
  cd ray\python
  pip install -e . --verbose

Advanced build options
----------------------

Environment variables that influence builds

By default, Ray builds with optimizations, which can take a long time and
interfere with debugging. To perform fast, debug, or optimized builds,
run the following (via ``-c`` ``fastbuild``/``dbg``/``opt``, respectively):

.. code-block:: shell

 bazel run -c fastbuild //:gen_ray_pkg

This rebuilds Ray with the appropriate options (which might take a while).
If you need to build all targets, use ``bazel build //:all`` instead of
``bazel run //:gen_ray_pkg``.

To make this change permanent, you can add an option such as the following
line to your user-level ``~/.bazelrc`` file (not to be confused with the
workspace-level ``.bazelrc`` file):

.. code-block:: shell

 build --compilation_mode=fastbuild

If you do so, remember to revert this change, unless you want it to affect
all of your development in the future.

Using ``dbg`` instead of ``fastbuild`` generates more debug information,
which can make it easier to debug with a debugger like ``gdb``.

Using a local repository for dependencies

Install dependencies for the linter (``pre-commit``):

.. code-block:: shell

  pip install -c python/requirements_compiled.txt pre-commit
  pre-commit install

Install dependencies for running Ray unit tests under ``python/ray/tests``:

.. code-block:: shell

 pip install -c python/requirements_compiled.txt -r python/requirements/test-requirements.txt

Requirement files for running Ray Data / ML library tests are under ``python/requirements/``.

Pre-commit hooks
~~~~~~~~~~~~~~~~

Ray uses pre-commit hooks with `the pre-commit python package <https://pre-commit.com/>`_.
The ``.pre-commit-config.yaml`` file configures all the linting and formatting checks.
To start using ``pre-commit``:

.. code-block:: shell

   pip install pre-commit
   pre-commit install

This installs pre-commit into the current environment and enables pre-commit checks every time
you commit new code changes with git. To temporarily skip pre-commit checks, use the ``-n`` or
``--no-verify`` flag when committing:

.. code-block:: shell

   git commit -n

If you encounter any issues with ``pre-commit``, please `report an issue here`_.

.. _report an issue here: https://github.com/ray-project/ray/issues/new?template=bug-report.yml


Building the docs
-----------------

To learn more about building the docs refer to `Contributing to the Ray Documentation`_.

.. _Contributing to the Ray Documentation: https://docs.ray.io/en/master/ray-contribute/docs.html


Troubleshooting
---------------

If importing Ray (``python3 -c "import ray"``) in your development clone results
in this error:

.. code-block:: python

  Traceback (most recent call last):
    File "<string>", line 1, in <module>
    File ".../ray/python/ray/__init__.py", line 63, in <module>
      import ray._raylet  # noqa: E402
    File "python/ray/_raylet.pyx", line 98, in init ray._raylet
      import ray.memory_monitor as memory_monitor
    File ".../ray/python/ray/memory_monitor.py", line 9, in <module>
      import psutil  # noqa E402
    File ".../ray/python/ray/thirdparty_files/psutil/__init__.py", line 159, in <module>
      from . import _psosx as _psplatform
    File ".../ray/python/ray/thirdparty_files/psutil/_psosx.py", line 15, in <module>
      from . import _psutil_osx as cext
  ImportError: cannot import name '_psutil_osx' from partially initialized module 'psutil' (most likely due to a circular import) (.../ray/python/ray/thirdparty_files/psutil/__init__.py)

Run the following commands:

.. code-block:: bash

  rm -rf python/ray/thirdparty_files/
  python3 -m pip install psutil