From 623e893dbab1f7880b0bbba8d1be30915b7d8f41 Mon Sep 17 00:00:00 2001 From: Dean Wampler Date: Mon, 6 Jul 2020 07:03:28 -0700 Subject: [PATCH] Refined the instructions about Windows and also Python versions --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 53 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index b48eeb3..d0c8ad7 100644 --- a/README.md +++ b/README.md @@ -28,19 +28,33 @@ However, consider cloning or downloading a release of the tutorial notebooks and ## Setup for a Local Machine -> **WARNING:** Ray does not currently run on Windows (we're close...). [Contact Anyscale](mailto:academy@anyscale.com) for a free hosted option. +> **Note:** Ray support for Windows is experimental. See [these release notes](https://github.com/ray-project/ray/releases/tag/ray-0.8.6) for details. Alternatively, [Contact Anyscale](mailto:academy@anyscale.com) for a free hosted option for these tutorials. -If you are using MacOS or Linux, follow these instructions. Note that the setup commands can take a while to finish. +Follow these instructions to use the tutorials. Note that some commands can take a while to finish. Clone the [Academy GitHub repo](https://github.com/anyscale/academy) or [download the latest release](https://github.com/anyscale/academy/releases). Now install the dependencies using either [Anaconda](https://www.anaconda.com/) or `pip` in your Python environment. We recommend using Anaconda. +### Which Python Version? + +Python 3.7 is recommended. While Ray supports Python 3.6, a user reported a problem using _locales_. Specifically, the following code throws an error: + +```python +import locale +locale.setlocale(locale.LC_ALL, locale.getlocale()) +``` + +This tutorial doesn't use _locales_ specifically, but you may run into problems with your default locale. + +While Ray supports Python 3.8, some dependencies used in `RLlib` (the Ray reinforcement library) are not yet supported for 3.8, at the time of this writing. + + ### Using Anaconda If you need to install Anaconda, follow the instructions [here](https://www.anaconda.com/distribution/). If you already have Anaconda installed, consider running `conda upgrade --all`. -Run the following commands in the root directory of this project. First, use `conda` to install the other dependencies, including Ray. Then activate the newly-created environment, named `anyscale-academy`. Finally, run a provided script to install a graphing library extension in Jupyter Lab and perform other tasks. +Run the following commands in the root directory of this project. First, use `conda` to install the other dependencies, including Ray. Then activate the newly-created environment, named `anyscale-academy`. Finally, run the provided `tools/fix-jupyter.sh` script to install a graphing library extension in Jupyter Lab and perform other tasks. ```shell conda env create -f environment.yml @@ -48,7 +62,9 @@ conda activate anyscale-academy tools/fix-jupyter.sh ``` -Note that Python 3.7 is used. While Ray supports Python 3.8, some dependencies used in `RLlib` (the Ray reinforcement library) are not yet supported for 3.8. +If you are using Windows, see the _Fixing Jupyter Lab on Windows_ section below for an alternative to using `tools/fix-jupyter.sh`. + +Note that Python 3.7 is used. You can delete the environment later with the following command: @@ -60,7 +76,8 @@ conda env remove --name anyscale-academy If you don't use Anaconda, you'll have to install these prerequisites first: -* Python 3.6 or 3.7: While Ray supports Python 3.8, some dependencies used in `RLlib` (the Ray reinforcement library) and other dependencies are not yet supported for 3.8. +* Python 3.7: + * See notes above about problems with 3.6 and 3.8. Don't use 3.8, but 3.6 may work for you. * The version of Python that comes with your operating system is probably too old. Try `python --version` to see what you have. * Installation instructions are at [python.org](https://www.python.org/downloads/). * Pip: A recent version - consider upgrading if it's not the latest version. @@ -68,16 +85,42 @@ If you don't use Anaconda, you'll have to install these prerequisites first: * Node.js: Required for some of the Jupyter Lab graphics extensions we use. * Installation instructions are [here](https://nodejs.org/en/). -Now run the following commands in the root directory of this project to complete the setup. First, run a `pip` command to install the rest of the libraries required for these tutorials, including Ray. Then, run a provided script to install a graphing library extension in Jupyter Lab and perform other tasks. +Next, run the following commands in the root directory of this project to complete the setup. First, run the `pip` command to install the rest of the libraries required for these tutorials, including Ray. Then, run the provided script to install a graphing library extension in Jupyter Lab and perform other tasks. ```shell pip install -r requirements.txt tools/fix-jupyter.sh ``` +If you are using Windows, see the _Fixing Jupyter Lab on Windows_ section below for an alternative to using `tools/fix-jupyter.sh`. + +### Fixing Jupyter Lab on Windows + +The `tools/fix-jupyter.sh` shell script runs the following commands. If you are using Windows, run them yourself as shown here. + +First, see if the following `pyviz` extension is installed: + +``` +jupyter labextension check --installed "@pyviz/jupyterlab_pyviz" +``` + +If not, run this command: + +``` +jupyter labextension install "@pyviz/jupyterlab_pyviz" +``` + +Finally, run these commands: + +``` +jupyter labextension update --all +jupyter lab build +jupyter labextension list +``` + ## Final Notes for Local Installation -The lessons will start a local Ray "cluster" (one node) on your machine. When you are finished with the tutorials, run the following command to shut down Ray: +The tutorials will start a local Ray "cluster" (one node) on your machine. When you are finished with the tutorials, run the following command to shut down Ray: ```shell ray stop @@ -85,12 +128,14 @@ ray stop Also, when you have finished working through the tutorials, run the script `tools/cleanup.sh`, which prints temporary files, checkpoints, etc. that were created during the lessons. You might want to remove these as they can add up to 100s of MBs. -If you decide to delete all the files and directories listed, the following script will do it: +If you decide to delete all the files and directories listed, the following `bash` command will do it: ```shell tools/cleanup.sh | while read x; do rm -rf $x; done ``` +> **Note:** A Windows version of this script is TBD. + ## Launching the Tutorials The previous steps installed [Jupyter Lab](https://jupyterlab.readthedocs.io/en/stable/), the notebook-based environment we'll use for all the lessons. To start run the following command in the project root directory: @@ -120,10 +165,6 @@ Here is a recommended reading list, based on your interests: See the [Overview notebook](Overview.ipynb) for detailed, up-to-date descriptions for each tutorial and the lessons it contains. -## Notes - -* We use Python 3.7, because a dependency of `RLlib`, `atari-py`, doesn't have a wheel available for Python 3.8 at this time. - ## Troubleshooting See the [Troubleshooting, Tips, and Tricks](reference/Troubleshooting-Tips-Tricks.ipynb) notebook.