diff --git a/docs/install/index.md b/docs/install/index.md index 5fef5ca47e57..ac7bd048a588 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -26,6 +26,7 @@ c_plus_plus.md centos_setup.md download.md + install-jetson.md java_setup.md osx_setup.md scala_setup.md @@ -1447,89 +1448,9 @@ You are now ready to run MXNet on your Raspberry Pi device. You can get started
-# Nvidia Jetson TX family +# NVIDIA Jetson Devices -MXNet supports the Ubuntu Arch64 based operating system so you can run MXNet on NVIDIA Jetson Devices. - -These instructions will walk through how to build MXNet for the Pascal based [NVIDIA Jetson TX2](http://www.nvidia.com/object/embedded-systems-dev-kits-modules.html) and install the corresponding python language bindings. - -For the purposes of this install guide we will assume that CUDA is already installed on your Jetson device. - -**Install MXNet** - -Installing MXNet is a two-step process: - -1. Build the shared library from the MXNet C++ source code. -2. Install the supported language-specific packages for MXNet. - -**Step 1** Build the Shared Library - -You need the following additional dependencies: - -- Git (to pull code from GitHub) - -- libatlas (for linear algebraic operations) - -- libopencv (for computer vision operations) - -- python pip (to load relevant python packages for our language bindings) - -Install these dependencies using the following commands in any directory: - -``` - sudo apt-get update - sudo apt-get -y install git build-essential libatlas-base-dev libopencv-dev graphviz python-pip - sudo pip install pip --upgrade - sudo pip install setuptools numpy --upgrade - sudo pip install graphviz==0.8.4 \ - jupyter -``` - -Clone the MXNet source code repository using the following `git` command in your home directory: -``` - git clone https://github.com/apache/incubator-mxnet.git --recursive - cd incubator-mxnet -``` - -Edit the Makefile to install the MXNet with CUDA bindings to leverage the GPU on the Jetson: -``` - cp make/crosscompile.jetson.mk config.mk -``` - -Edit the Mshadow Makefile to ensure MXNet builds with Pascal's hardware level low precision acceleration by editing 3rdparty/mshadow/make/mshadow.mk and adding the following after line 122: -``` -MSHADOW_CFLAGS += -DMSHADOW_USE_PASCAL=1 -``` - -Now you can build the complete MXNet library with the following command: -``` - make -j $(nproc) -``` - -Executing this command creates a file called `libmxnet.so` in the mxnet/lib directory. - -**Step 2** Install MXNet Python Bindings - -To install Python bindings run the following commands in the MXNet directory: - -``` - cd python - pip install --upgrade pip - pip install -e . -``` - -Note that the `-e` flag is optional. It is equivalent to `--editable` and means that if you edit the source files, these changes will be reflected in the package installed. - -Add the mxnet folder to the path: - -``` - cd .. - export MXNET_HOME=$(pwd) - echo "export PYTHONPATH=$MXNET_HOME/python:$PYTHONPATH" >> ~/.rc - source ~/.rc -``` - -You are now ready to run MXNet on your NVIDIA Jetson TX2 device. +To install MXNet on a Jetson TX or Nano, please refer to the [Jetson installation guide](install-jetson.html).
diff --git a/docs/install/install-jetson.md b/docs/install/install-jetson.md new file mode 100644 index 000000000000..a93f930a8182 --- /dev/null +++ b/docs/install/install-jetson.md @@ -0,0 +1,289 @@ + + + + + + + + + + + + + + + + + +# Install MXNet on a Jetson + +MXNet supports the Ubuntu Arch64 based operating system so you can run MXNet on NVIDIA Jetson Devices, such as the [TX2](http://www.nvidia.com/object/embedded-systems-dev-kits-modules.html) or [Nano](https://developer.nvidia.com/embedded/learn/get-started-jetson-nano-devkit). + +These instructions will walk through how to build MXNet and install the corresponding language bindings. Python is the default binding, but you may also try out one of the many language bindings MXNet has to offer. These instructions also cover how to setup MXNet's Java Inference API. + +For the purposes of this install guide we will assume that CUDA is already installed on your Jetson device. The disk image provided by NVIDIA's getting started guides will have the Jetson toolkit preinstalled, and this also includes CUDA. You should double check what versions are installed and which version you plan to use. + +You have several options for installing MXNet: +1. Use a Jetson MXNet pip wheel for Python development. +2. Use precompiled Jetson MXNet binaries. +3. Build MXNet from source + * On a faster Linux computer using cross-compilation + * On the Jetson itself (very slow and not recommended) + + +## Prerequisites +To build from source or to use the Python wheel, you must install the following dependencies on your Jetson. +Cross-compiling will require dependencies installed on that machine as well. + +### Python API + +To use the Python API you need the following dependencies: + +```bash +sudo apt update +sudo apt -y install \ + build-essential \ + git \ + graphviz \ + libatlas-base-dev \ + libopencv-dev \ + python-pip + +sudo pip install --upgrade \ + pip \ + setuptools + +sudo pip install \ + graphviz==0.8.4 \ + jupyter \ + numpy==1.15.2 +``` + +If you plan to cross-compile you will need to install these dependencies on that computer as well. + + + +### Configure CUDA + +You can check to see what version of CUDA is running with `nvcc`. + +```bash +nvcc --version +``` + +To switch CUDA versions on a device or computer that has more than one version installed, use the following and replace the version as appropriate. + +```bash +sudo rm /usr/local/cuda +sudo ln -s /usr/local/cuda-10.0 /usr/local/cuda +``` + +**Note:** When cross-compiling, change the CUDA version on the host computer you're using to match the version you're running on your Jetson device. +**Note:** CUDA 10.1 is recommended but doesn't ship with the Nano's SD card image. You may want to go through CUDA upgrade steps first. + +### Download the source & setup some environment variables: + +These steps are optional, but some of the following instructions expect MXNet source files and the `MXNET_HOME` environment variable. + +Clone the MXNet source code repository using the following `git` command in your home directory: + +```bash +git clone --recursive https://github.com/apache/incubator-mxnet.git mxnet +cd mxnet +``` + +Setup your environment variables for MXNet. + +```bash +cd .. +export MXNET_HOME=$(pwd) +echo "export PYTHONPATH=$MXNET_HOME/python:$PYTHONPATH" >> ~/.rc +source ~/.rc +``` + +**Note:** Change the `~/.rc` steps according to how you prefer to use your shell. Otherwise, your environment variables will be gone after you logout. + + +## Install MXNet for Python + +To use a prepared Python wheel, download it to your Jetson, and run it. +* [MXNet 1.4.0 - Python 3](https://s3.us-east-2.amazonaws.com/mxnet-public/install/jetson/1.4.0/mxnet-1.4.0-cp36-cp36m-linux_aarch64.whl) +* [MXNet 1.4.0 - Python 2](https://s3.us-east-2.amazonaws.com/mxnet-public/install/jetson/1.4.0/mxnet-1.4.0-cp27-cp27mu-linux_aarch64.whl) + + +It should download the required dependencies, but if you have issues, +install the dependencies in the prerequisites section, then run the pip wheel. + +```bash +sudo pip install mxnet-1.4.0-cp36-cp36m-linux_aarch64.whl +``` + + + +## Use a Pre-compiled MXNet Binary + +If you want to just use a pre-compiled binary you can download it from S3: +* https://s3.us-east-2.amazonaws.com/mxnet-public/install/jetson/1.4.1/libmxnet.so + +Place this file in `$MXNET_HOME/lib`. + +To use this with the MXNet Python binding, you must match the source directory's checked out version with the binary's source version, then install it with pip. + +```bash +cd $MXNET_HOME +git checkout v1.4.x +git submodule update --init +cd python +sudo pip install -e . +``` + +## Build MXNet from Source + +Installing MXNet from source is a two-step process: + +1. Build the shared library from the MXNet C++ source code. +2. Install the supported language-specific packages for MXNet. + +You can use a Docker method or you can build from source manually. + +### Docker + +You must have installed Docker and be able to run `docker` without `sudo`. +Follow these [setup instructions to get to this point](https://docs.docker.com/install/linux/#manage-docker-as-a-non-root-user). +Then run the following to execute cross-compilation via Docker. + +```bash +$MXNET_HOME/ci/build.py -p jetson +``` + +### Manual + +**Step 1** Build the Shared Library + +(Skip this sub-step for compiling on the Jetson device directly.) +Edit the Makefile to install the MXNet with CUDA bindings to leverage the GPU on the Jetson: + +```bash +cp $MXNET_HOME/make/crosscompile.jetson.mk config.mk +``` + +Now edit `config.mk` to make some additional changes for the Nano. Update the following settings: + +1. Update the CUDA path. `USE_CUDA_PATH = /usr/local/cuda` +2. Add `-gencode arch=compute-63, code=sm_62` to the `CUDA_ARCH` setting. +3. Update the NVCC settings. `NVCCFLAGS := -m64` +4. (optional, but recommended) Turn on OpenCV. `USE_OPENCV = 1` + +Now edit the Mshadow Makefile to ensure MXNet builds with Pascal's hardware level low precision acceleration by editing `3rdparty/mshadow/make/mshadow.mk`. +The last line has `MSHADOW_USE_PASCAL` set to `0`. Change this to `1` to enable it. + +```bash +MSHADOW_CFLAGS += -DMSHADOW_USE_PASCAL=1 +``` + +Now you can build the complete MXNet library with the following command: + +```bash +cd $MXNET_HOME +make -j $(nproc) +``` + +Executing this command creates a file called `libmxnet.so` in the `mxnet/lib` directory. + +**Step 2** Install MXNet Python Bindings (optional) + +To install Python bindings run the following commands in the MXNet directory: + +```bash +cd $MXNET_HOME/python +sudo pip install -e . +``` + +Note that the `-e` flag is optional. It is equivalent to `--editable` and means that if you edit the source files, these changes will be reflected in the package installed. + +**Step 3** Install the MXNet Java & Scala Bindings (optional) + +Change directories to `scala-package` and run `mvn install`. + +```bash +cd $MXNET_HOME/scala-package +mvn install +``` + +This creates the required `.jar` file to use in your Java or Scala projects. + +## Conclusion and Next Steps + +You are now ready to run MXNet on your NVIDIA Jetson TX2 or Nano device. +You can verify your MXNet Python installation with the following: + +```python +import mxnet +mxnet.__version__ +``` + +You can also verify MXNet can use your GPU with the following test: + +```python +import mxnet as mx +a = mx.nd.ones((2, 3), mx.gpu()) +b = a * 2 + 1 +b.asnumpy() +``` + +If everything is working, it will report the version number. +For assistance, head over to the [MXNet Forum](https://discuss.mxnet.io/).