Update Setup_TensorFlow.md

Setup_TensorFlow.md

@@ -1,135 +1,237 @@
-_From TensorFlow Official docs_
+From Tensorflow Official doc
 
-# Download and Setup <a class="md-anchor" id="AUTOGENERATED-download-and-setup"></a>
+# Download and Setup
 
-You can install TensorFlow using our provided binary packages or from source.
+You can install TensorFlow either from our provided binary packages or from the
+github source.
 
-## Binary Installation <a class="md-anchor" id="AUTOGENERATED-binary-installation"></a>
+## Requirements
 
-The TensorFlow Python API currently requires Python 2.7: we are
-[working](https://github.com/tensorflow/tensorflow/issues/1) on adding support
-for Python 3.
+The TensorFlow Python API supports Python 2.7 and Python 3.3+.
 
-The simplest way to install TensorFlow is using
-[pip](https://pypi.python.org/pypi/pip) for both Linux and Mac.
+The GPU version (Linux only) requires the Cuda Toolkit >= 7.0 and cuDNN >=
+v2.  Please see [Cuda installation](#optional-install-cuda-gpus-on-linux)
+for details.
+
+## Overview
+
+We support different ways to install TensorFlow:
+
+*  [Pip install](#pip-installation): Install TensorFlow on your machine, possibly
+   upgrading previously installed Python packages.  May impact existing
+   Python programs on your machine.
+*  [Virtualenv install](#virtualenv-installation): Install TensorFlow in its own
+   directory, not impacting any existing Python programs on your machine.
+*  [Docker install](#docker-installation): Run TensorFlow in a Docker container
+   isolated from all other programs on your machine.
+
+If you are familiar with Pip, Virtualenv, or Docker, please feel free to adapt
+the instructions to your particular needs.  The names of the pip and Docker
+images are listed in the corresponding installation sections.
 
 If you encounter installation errors, see
-[common problems](#common_install_problems) for some solutions. To simplify
-installation, please consider using our virtualenv-based instructions
-[here](#virtualenv_install).
+[common problems](#common-problems) for some solutions.
+
+## Pip Installation
 
-### Ubuntu/Linux 64-bit <a class="md-anchor" id="AUTOGENERATED-ubuntu-linux-64-bit"></a>
+[Pip](https://en.wikipedia.org/wiki/Pip_(package_manager)) is a package
+management system used to install and manage software packages written in
+Python.
+
+The packages that will be installed or upgraded during the pip install are listed in the
+[REQUIRED_PACKAGES section of setup.py](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/pip_package/setup.py)
+
+Install pip (or pip3 for python3) if it is not already installed:
 
 ```bash
-# For CPU-only version
-$ pip install https://storage.googleapis.com/tensorflow/linux/cpu/tensorflow-0.5.0-cp27-none-linux_x86_64.whl
+# Ubuntu/Linux 64-bit
+$ sudo apt-get install python-pip python-dev
 
-# For GPU-enabled version (only install this version if you have the CUDA sdk installed)
-$ pip install https://storage.googleapis.com/tensorflow/linux/gpu/tensorflow-0.5.0-cp27-none-linux_x86_64.whl
+# Mac OS X
+$ sudo easy_install pip
 ```
 
-### Mac OS X <a class="md-anchor" id="AUTOGENERATED-mac-os-x"></a>
-
-On OS X, we recommend installing [homebrew](http://brew.sh) and `brew install
-python` before proceeding, or installing TensorFlow within [virtualenv](#virtualenv_install).
+Install TensorFlow:
 
 ```bash
-# Only CPU-version is available at the moment.
-$ pip install https://storage.googleapis.com/tensorflow/mac/tensorflow-0.5.0-py2-none-any.whl
-```
+# Ubuntu/Linux 64-bit, CPU only:
+$ sudo pip install --upgrade https://storage.googleapis.com/tensorflow/linux/cpu/tensorflow-0.7.1-cp27-none-linux_x86_64.whl
 
-## Docker-based installation <a class="md-anchor" id="AUTOGENERATED-docker-based-installation"></a>
+# Ubuntu/Linux 64-bit, GPU enabled:
+$ sudo pip install --upgrade https://storage.googleapis.com/tensorflow/linux/gpu/tensorflow-0.7.1-cp27-none-linux_x86_64.whl
 
-We also support running TensorFlow via [Docker](http://docker.com/), which lets
-you avoid worrying about setting up dependencies.
+# Mac OS X, CPU only:
+$ sudo easy_install --upgrade six
+$ sudo pip install --upgrade https://storage.googleapis.com/tensorflow/mac/tensorflow-0.7.1-cp27-none-any.whl
+```
 
-First, [install Docker](http://docs.docker.com/engine/installation/). Once
-Docker is up and running, you can start a container with one command:
+For python3:
 
 ```bash
-$ docker run -it b.gcr.io/tensorflow/tensorflow
+# Ubuntu/Linux 64-bit, CPU only:
+$ sudo pip3 install --upgrade https://storage.googleapis.com/tensorflow/linux/cpu/tensorflow-0.7.1-cp34-none-linux_x86_64.whl
+
+# Ubuntu/Linux 64-bit, GPU enabled:
+$ sudo pip3 install --upgrade https://storage.googleapis.com/tensorflow/linux/gpu/tensorflow-0.7.1-cp34-none-linux_x86_64.whl
+
+# Mac OS X, CPU only:
+$ sudo easy_install --upgrade six
+$ sudo pip3 install --upgrade https://storage.googleapis.com/tensorflow/mac/tensorflow-0.7.1-cp35-none-any.whl
 ```
 
-This will start a container with TensorFlow and all its dependencies already
-installed.
+NOTE: If you are upgrading from a previous installation of TensorFlow < 0.7.1,
+you should uninstall the previous TensorFlow *and protobuf* using `pip
+uninstall` first to make sure you get a clean installation of the updated
+protobuf dependency.
 
-### Additional images <a class="md-anchor" id="AUTOGENERATED-additional-images"></a>
 
-The default Docker image above contains just a minimal set of libraries for
-getting up and running with TensorFlow. We also have the following container,
-which you can use in the `docker run` command above:
+You can now [test your installation](#test-the-tensorflow-installation).
 
-* `b.gcr.io/tensorflow/tensorflow-full`: Contains a complete TensorFlow source
-  installation, including all utilities needed to build and run TensorFlow. This
-  makes it easy to experiment directly with the source, without needing to
-  install any of the dependencies described above.
+## Virtualenv installation
 
-## VirtualEnv-based installation <a class="md-anchor" id="virtualenv_install"></a>
+[Virtualenv](http://docs.python-guide.org/en/latest/dev/virtualenvs/) is a tool
+to keep the dependencies required by different Python projects in separate
+places.  The Virtualenv installation of TensorFlow will not override
+pre-existing version of the Python packages needed by TensorFlow.
 
-We recommend using [virtualenv](https://pypi.python.org/pypi/virtualenv) to
-create an isolated container and install TensorFlow in that container -- it is
-optional but makes verifying installation issues easier.
+With [Virtualenv](https://pypi.python.org/pypi/virtualenv) the installation is
+as follows:
 
-First, install all required tools:
+*  Install pip and Virtualenv.
+*  Create a Virtualenv environment.
+*  Activate the Virtualenv environment and install TensorFlow in it.
+*  After the install you will activate the Virtualenv environment each time you
+   want to use TensorFlow.
+
+Install pip and Virtualenv:
 
 ```bash
-# On Linux:
+# Ubuntu/Linux 64-bit
 $ sudo apt-get install python-pip python-dev python-virtualenv
 
-# On Mac:
-$ sudo easy_install pip  # If pip is not already installed
+# Mac OS X
+$ sudo easy_install pip
 $ sudo pip install --upgrade virtualenv
 ```
 
-Next, set up a new virtualenv environment.  To set it up in the
-directory `~/tensorflow`, run:
+Create a Virtualenv environment in the directory `~/tensorflow`:
 
 ```bash
 $ virtualenv --system-site-packages ~/tensorflow
-$ cd ~/tensorflow
 ```
 
-Then activate the virtualenv:
+Activate the environment and use pip to install TensorFlow inside it:
 
 ```bash
-$ source bin/activate  # If using bash
-$ source bin/activate.csh  # If using csh
+$ source ~/tensorflow/bin/activate  # If using bash
+$ source ~/tensorflow/bin/activate.csh  # If using csh
 (tensorflow)$  # Your prompt should change
+
+# Ubuntu/Linux 64-bit, CPU only:
+(tensorflow)$ pip install --upgrade https://storage.googleapis.com/tensorflow/linux/cpu/tensorflow-0.7.1-cp27-none-linux_x86_64.whl
+
+# Ubuntu/Linux 64-bit, GPU enabled:
+(tensorflow)$ pip install --upgrade https://storage.googleapis.com/tensorflow/linux/gpu/tensorflow-0.7.1-cp27-none-linux_x86_64.whl
+
+# Mac OS X, CPU only:
+(tensorflow)$ pip install --upgrade https://storage.googleapis.com/tensorflow/mac/tensorflow-0.7.1-cp27-none-any.whl
 ```
 
-Inside the virtualenv, install TensorFlow:
+and again for python3:
 
 ```bash
-# For CPU-only linux x86_64 version
-(tensorflow)$ pip install --upgrade https://storage.googleapis.com/tensorflow/linux/cpu/tensorflow-0.5.0-cp27-none-linux_x86_64.whl
+$ source ~/tensorflow/bin/activate  # If using bash
+$ source ~/tensorflow/bin/activate.csh  # If using csh
+(tensorflow)$  # Your prompt should change
+
+# Ubuntu/Linux 64-bit, CPU only:
+(tensorflow)$ pip install --upgrade https://storage.googleapis.com/tensorflow/linux/cpu/tensorflow-0.7.1-cp34-none-linux_x86_64.whl
 
-# For GPU-enabled linux x86_64 version
-(tensorflow)$ pip install --upgrade https://storage.googleapis.com/tensorflow/linux/gpu/tensorflow-0.5.0-cp27-none-linux_x86_64.whl
+# Ubuntu/Linux 64-bit, GPU enabled:
+(tensorflow)$ pip install --upgrade https://storage.googleapis.com/tensorflow/linux/gpu/tensorflow-0.7.1-cp34-none-linux_x86_64.whl
 
-# For Mac CPU-only version
-(tensorflow)$ pip install --upgrade https://storage.googleapis.com/tensorflow/mac/tensorflow-0.5.0-py2-none-any.whl
+# Mac OS X, CPU only:
+(tensorflow)$ pip3 install --upgrade https://storage.googleapis.com/tensorflow/mac/tensorflow-0.7.1-cp35-none-any.whl
 ```
 
-Make sure you have downloaded the source code for TensorFlow, and then you can
-then run an example TensorFlow program like:
+With the Virtualenv environment activated, you can now
+[test your installation](#test-the-tensorflow-installation).
 
-```bash
-(tensorflow)$ cd tensorflow/models/image/mnist
-(tensorflow)$ python convolutional.py
+When you are done using TensorFlow, deactivate the environment.
 
-# When you are done using TensorFlow:
-(tensorflow)$ deactivate  # Deactivate the virtualenv
+```bash
+(tensorflow)$ deactivate
 
 $  # Your prompt should change back
 ```
 
-## Try your first TensorFlow program <a class="md-anchor" id="AUTOGENERATED-try-your-first-tensorflow-program"></a>
+To use TensorFlow later you will have to activate the Virtualenv environment again:
+
+```bash
+$ source ~/tensorflow/bin/activate  # If using bash.
+$ source ~/tensorflow/bin/activate.csh  # If using csh.
+(tensorflow)$  # Your prompt should change.
+# Run Python programs that use TensorFlow.
+...
+# When you are done using TensorFlow, deactivate the environment.
+(tensorflow)$ deactivate
+```
+
+## Docker installation
+
+[Docker](http://docker.com/) is a system to build self contained versions of a
+Linux operating system running on your machine.  When you install and run
+TensorFlow via Docker it completely isolates the installation from pre-existing
+packages on your machine.
+
+We provide 4 Docker images:
+
+* `b.gcr.io/tensorflow/tensorflow`: TensorFlow CPU binary image.
+* `b.gcr.io/tensorflow/tensorflow:latest-devel`: CPU Binary image plus source
+code.
+* `b.gcr.io/tensorflow/tensorflow:latest-gpu`: TensorFlow GPU binary image.
+* `b.gcr.io/tensorflow/tensorflow:latest-devel-gpu`: GPU Binary image plus source
+code.
+
+We also have tags with `latest` replaced by a released version (e.g., `0.7.1-gpu`).
+
+With Docker the installation is as follows:
+
+*  Install Docker on your machine.
+*  Create a [Docker
+group](http://docs.docker.com/engine/installation/ubuntulinux/#create-a-docker-group)
+to allow launching containers without `sudo`.
+*  Launch a Docker container with the TensorFlow image.  The image
+   gets downloaded automatically on first launch.
+
+See [installing Docker](http://docs.docker.com/engine/installation/) for instructions
+on installing Docker on your machine.
+
+After Docker is installed, launch a Docker container with the TensorFlow binary
+image as follows.
+
+```bash
+$ docker run -it b.gcr.io/tensorflow/tensorflow
+```
+
+If you're using a container with GPU support, some additional flags must be
+passed to expose the GPU device to the container. For the default config, we
+include a
+[script](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/docker/docker_run_gpu.sh)
+in the repo with these flags, so the command-line would look like
+
+```bash
+$ path/to/repo/tensorflow/tools/docker/docker_run_gpu.sh b.gcr.io/tensorflow/tensorflow:gpu
+```
+
+You can now [test your installation](#test-the-tensorflow-installation) within the Docker container.
 
-### (Optional) Enable GPU Support <a class="md-anchor" id="AUTOGENERATED--optional--enable-gpu-support"></a>
+## Test the TensorFlow installation
 
-If you installed the GPU-enabled TensorFlow pip binary, you must have the
-correct versions of the CUDA SDK and CUDNN installed on your
-system.  Please see [the CUDA installation instructions](#install_cuda).
+### (Optional, Linux) Enable GPU Support
+
+If you installed the GPU version of TensorFlow, you must also install the Cuda
+Toolkit 7.0 and cuDNN v2.  Please see [Cuda installation](#optional-install-cuda-gpus-on-linux).
 
 You also need to set the `LD_LIBRARY_PATH` and `CUDA_HOME` environment
 variables.  Consider adding the commands below to your `~/.bash_profile`.  These
@@ -140,44 +242,86 @@ export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/usr/local/cuda/lib64"
 export CUDA_HOME=/usr/local/cuda
 ```
 
-### Run TensorFlow <a class="md-anchor" id="AUTOGENERATED-run-tensorflow"></a>
+### Run TensorFlow from the Command Line
+
+See [common problems](#common-problems) if an error happens.
 
-Open a python terminal:
+Open a terminal and type the following:
 
 ```bash
 $ python
-
+...
 >>> import tensorflow as tf
 >>> hello = tf.constant('Hello, TensorFlow!')
 >>> sess = tf.Session()
->>> print sess.run(hello)
+>>> print(sess.run(hello))
 Hello, TensorFlow!
 >>> a = tf.constant(10)
 >>> b = tf.constant(32)
->>> print sess.run(a+b)
+>>> print(sess.run(a + b))
 42
 >>>
+```
+
+### Run a TensorFlow demo model
+
+All TensorFlow packages, including the demo models, are installed in the Python library.
+The exact location of the Python library depends on your system, but is usually one of:
+
+```bash
+/usr/local/lib/python2.7/dist-packages/tensorflow
+/usr/local/lib/python2.7/site-packages/tensorflow
+```
+
+You can find out the directory with the following command (make sure to use the Python you installed TensorFlow to, for example, use `python3` instead of `python` if you installed for Python 3):
 
+```bash
+$ python -c 'import os; import inspect; import tensorflow; print(os.path.dirname(inspect.getfile(tensorflow)))'
 ```
 
-## Installing from sources <a class="md-anchor" id="source"></a>
+The simple demo model for classifying handwritten digits from the MNIST dataset
+is in the sub-directory `models/image/mnist/convolutional.py`.  You can run it from the command
+line as follows (make sure to use the Python you installed TensorFlow with):
 
-### Clone the TensorFlow repository <a class="md-anchor" id="AUTOGENERATED-clone-the-tensorflow-repository"></a>
+```bash
+# Using 'python -m' to find the program in the python search path:
+$ python -m tensorflow.models.image.mnist.convolutional
+Extracting data/train-images-idx3-ubyte.gz
+Extracting data/train-labels-idx1-ubyte.gz
+Extracting data/t10k-images-idx3-ubyte.gz
+Extracting data/t10k-labels-idx1-ubyte.gz
+...etc...
+
+# You can alternatively pass the path to the model program file to the python
+# interpreter (make sure to use the python distribution you installed
+# TensorFlow to, for example, .../python3.X/... for Python 3).
+$ python /usr/local/lib/python2.7/dist-packages/tensorflow/models/image/mnist/convolutional.py
+...
+```
+
+## Installing from sources
+
+When installing from source you will build a pip wheel that you then install
+using pip. You'll need pip for that, so install it as described
+[above](#pip-installation).
+
+### Clone the TensorFlow repository
 
 ```bash
 $ git clone --recurse-submodules https://github.com/tensorflow/tensorflow
 ```
 
 `--recurse-submodules` is required to fetch the protobuf library that TensorFlow
-depends on.
+depends on. Note that these instructions will install the latest master branch
+of tensorflow. If you want to install a specific branch (such as a release branch),
+pass `-b <branchname>` to the `git clone` command.
 
-### Installation for Linux <a class="md-anchor" id="AUTOGENERATED-installation-for-linux"></a>
-
-#### Install Bazel <a class="md-anchor" id="AUTOGENERATED-install-bazel"></a>
+### Installation for Linux
 
+#### Install Bazel
 
 Follow instructions [here](http://bazel.io/docs/install.html) to install the
-dependencies for Bazel. Then download bazel version 0.1.1 using the
+dependencies for bazel. Then download the latest stable bazel version using the
 [installer for your system](https://github.com/bazelbuild/bazel/releases) and
 run the installer as mentioned there:
 
@@ -186,63 +330,97 @@ $ chmod +x PATH_TO_INSTALL.SH
 $ ./PATH_TO_INSTALL.SH --user
 ```
 
-Remember to replace `PATH_TO_INSTALL.SH` to point to the location where you
+Remember to replace `PATH_TO_INSTALL.SH` with the location where you
 downloaded the installer.
 
-Finally, follow the instructions in that script to place bazel into your binary
-path.
+Finally, follow the instructions in that script to place `bazel` into your
+binary path.
 
-#### Install other dependencies <a class="md-anchor" id="AUTOGENERATED-install-other-dependencies"></a>
+#### Install other dependencies
 
 ```bash
 $ sudo apt-get install python-numpy swig python-dev
 ```
 
-#### Optional: Install CUDA (GPUs on Linux) <a class="md-anchor" id="install_cuda"></a>
+#### Configure the installation
 
-In order to build or run TensorFlow with GPU support, both Cuda Toolkit 7.0 and
-CUDNN 6.5 V2 from NVIDIA need to be installed.
+Run the `configure` script at the root of the tree.  The configure script
+asks you for the path to your python interpreter and allows (optional)
+configuration of the CUDA libraries (see [below](#configure-tensorflows-canonical-view-of-cuda-libraries)).
 
-TensorFlow GPU support requires having a GPU card with NVidia Compute Capability >= 3.5.  Supported cards include but are not limited to:
+This step is used to locate the python and numpy header files.
+
+```bash
+$ ./configure
+Please specify the location of python. [Default is /usr/bin/python]:
+```
+
+#### Optional: Install CUDA (GPUs on Linux)
+
+In order to build or run TensorFlow with GPU support, both NVIDIA's Cuda Toolkit (>= 7.0) and
+cuDNN (>= v2) need to be installed.
+
+TensorFlow GPU support requires having a GPU card with NVidia Compute Capability >= 3.0.
+Supported cards include but are not limited to:
 
 * NVidia Titan
 * NVidia Titan X
 * NVidia K20
 * NVidia K40
 
-##### Download and install Cuda Toolkit 7.0 <a class="md-anchor" id="AUTOGENERATED-download-and-install-cuda-toolkit-7.0"></a>
+##### Download and install Cuda Toolkit
 
-https://developer.nvidia.com/cuda-toolkit-70
+https://developer.nvidia.com/cuda-downloads
 
 Install the toolkit into e.g. `/usr/local/cuda`
 
-##### Download and install CUDNN Toolkit 6.5 <a class="md-anchor" id="AUTOGENERATED-download-and-install-cudnn-toolkit-6.5"></a>
+##### Download and install cuDNN
 
-https://developer.nvidia.com/rdp/cudnn-archive
+https://developer.nvidia.com/cudnn
 
-Uncompress and copy the cudnn files into the toolkit directory.  Assuming the
-toolkit is installed in `/usr/local/cuda`:
+Uncompress and copy the cuDNN files into the toolkit directory.  Assuming the
+toolkit is installed in `/usr/local/cuda`, run the following commands (edited
+to reflect the cuDNN version you downloaded):
 
 ``` bash
 tar xvzf cudnn-6.5-linux-x64-v2.tgz
 sudo cp cudnn-6.5-linux-x64-v2/cudnn.h /usr/local/cuda/include
 sudo cp cudnn-6.5-linux-x64-v2/libcudnn* /usr/local/cuda/lib64
+sudo chmod a+r /usr/local/cuda/lib64/libcudnn*
 ```
 
-##### Configure TensorFlow's canonical view of Cuda libraries <a class="md-anchor" id="AUTOGENERATED-configure-tensorflow-s-canonical-view-of-cuda-libraries"></a>
-From the root of your source tree, run:
+##### Configure TensorFlow's canonical view of Cuda libraries
+
+When running the `configure` script from the root of your source tree, select
+the option `Y` when asked to build TensorFlow with GPU support. If you have 
+several versions of Cuda or cuDNN installed, you should definitely select
+one explicitly instead of relying on the system default. You should see
+prompts like the following:
 
 ``` bash
 $ ./configure
-Do you wish to build TensorFlow with GPU support? [y/n] y
+Please specify the location of python. [Default is /usr/bin/python]:
+Do you wish to build TensorFlow with GPU support? [y/N] y
 GPU support will be enabled for TensorFlow
 
-Please specify the location where CUDA 7.0 toolkit is installed. Refer to
-README.md for more details. [default is: /usr/local/cuda]: /usr/local/cuda
+Please specify the Cuda SDK version you want to use, e.g. 7.0. [Leave
+empty to use system default]: 7.5
 
-Please specify the location where CUDNN 6.5 V2 library is installed. Refer to
+Please specify the location where CUDA 7.5 toolkit is installed. Refer to
 README.md for more details. [default is: /usr/local/cuda]: /usr/local/cuda
 
+Please specify the Cudnn version you want to use. [Leave empty to use system
+default]: 4.0.4
+
+Please specify the location where the cuDNN 4.0.4 library is installed. Refer to
+README.md for more details. [default is: /usr/local/cuda]: /usr/local/cudnn-r4-rc/
+
+Please specify a list of comma-separated Cuda compute capabilities you want to
+build with. You can find the compute capability of your device at: 
+https://developer.nvidia.com/cuda-gpus.
+Please note that each additional compute capability significantly increases your
+build time and binary size. [Default is: \"3.5,5.2\"]: 3.5
+    
 Setting up Cuda include
 Setting up Cuda lib64
 Setting up Cuda bin
@@ -252,9 +430,11 @@ Configuration finished
 
 This creates a canonical set of symbolic links to the Cuda libraries on your system.
 Every time you change the Cuda library paths you need to run this step again before
-you invoke the bazel build command.
+you invoke the bazel build command. For the Cudnn libraries, use '6.5' for R2, '7.0'
+for R3, and '4.0.4' for R4-RC.
 
-##### Build your target with GPU support. <a class="md-anchor" id="AUTOGENERATED-build-your-target-with-gpu-support."></a>
+
+##### Build your target with GPU support
 From the root of your source tree, run:
 
 ```bash
@@ -270,69 +450,65 @@ $ bazel-bin/tensorflow/cc/tutorials_example_trainer --use_gpu
 
 Note that "--config=cuda" is needed to enable the GPU support.
 
-##### Enabling Cuda 3.0. <a class="md-anchor" id="AUTOGENERATED-enabling-cuda-3.0."></a>
-TensorFlow officially supports Cuda devices with 3.5 and 5.2 compute
-capabilities. In order to enable earlier Cuda devices such as Grid K520, you
-need to target Cuda 3.0. This can be done through TensorFlow unofficial
-settings with "configure".
-
-```bash
-$ TF_UNOFFICIAL_SETTING=1 ./configure
+##### Known issues
 
-# Same as the official settings above
+* Although it is possible to build both Cuda and non-Cuda configs under the same
+source tree, we recommend to run `bazel clean` when switching between these two
+configs in the same source tree.
 
-WARNING: You are configuring unofficial settings in TensorFlow. Because some
-external libraries are not backward compatible, these settings are largely
-untested and unsupported.
+* You have to run configure before running bazel build. Otherwise, the build
+will fail with a clear error message. In the future, we might consider making
+this more convenient by including the configure step in our build process.
 
-Please specify a list of comma-separated Cuda compute capabilities you want to
-build with. You can find the compute capability of your device at:
-https://developer.nvidia.com/cuda-gpus.
-Please note that each additional compute capability significantly increases
-your build time and binary size. [Default is: "3.5,5.2"]: 3.0
+### Installation for Mac OS X
 
-Setting up Cuda include
-Setting up Cuda lib64
-Setting up Cuda bin
-Setting up Cuda nvvm
-Configuration finished
-```
+We recommend using [homebrew](http://brew.sh) to install the bazel and SWIG
+dependencies, and installing python dependencies using easy_install or pip.
 
-##### Known issues <a class="md-anchor" id="AUTOGENERATED-known-issues"></a>
+Of course you can also install Swig from source without using homebrew. In that
+case, be sure to install its dependency [PCRE](http://www.pcre.org) and not PCRE2.
 
-* Although it is possible to build both Cuda and non-Cuda configs under the same
-source tree, we recommend to run "bazel clean" when switching between these two
-configs in the same source tree.
+#### Dependencies
 
-* You have to run configure before running bazel build. Otherwise, the build
-will fail with a clear error message. In the future, we might consider making
-this more conveninent by including the configure step in our build process,
-given necessary bazel new feature support.
+Follow instructions [here](http://bazel.io/docs/install.html) to install the
+dependencies for bazel. You can then use homebrew to install bazel and SWIG:
 
-### Installation for Mac OS X <a class="md-anchor" id="AUTOGENERATED-installation-for-mac-os-x"></a>
+```bash
+$ brew install bazel swig
+```
 
-Mac needs the same set of dependencies as Linux, however their installing those
-dependencies is different. Here is a set of useful links to help with installing
-the dependencies on Mac OS X :
+You can install the python dependencies using easy_install or pip. Using
+easy_install, run
 
-#### Bazel <a class="md-anchor" id="AUTOGENERATED-bazel"></a>
+```bash
+$ sudo easy_install -U six
+$ sudo easy_install -U numpy
+$ sudo easy_install wheel
+```
 
-Look for installation instructions for Mac OS X on
-[this](http://bazel.io/docs/install.html) page.
+We also recommend the [ipython](https://ipython.org) enhanced python shell, so
+best install that too:
 
-#### SWIG <a class="md-anchor" id="AUTOGENERATED-swig"></a>
+```bash
+$ sudo easy_install ipython
+```
 
-[Mac OS X installation](http://www.swig.org/Doc3.0/Preface.html#Preface_osx_installation).
+#### Configure the installation
 
-Notes : You need to install
-[PCRE](ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/) and *NOT* PCRE2.
+Run the `configure` script at the root of the tree.  The configure script
+asks you for the path to your python interpreter.
 
-#### Numpy <a class="md-anchor" id="AUTOGENERATED-numpy"></a>
+This step is used to locate the python and numpy header files.
 
-Follow installation instructions [here](http://docs.scipy.org/doc/numpy/user/install.html).
+```bash
+$ ./configure
+Please specify the location of python. [Default is /usr/bin/python]:
+Do you wish to build TensorFlow with GPU support? [y/N]
+```
 
+### Create the pip package and install
 
-### Create the pip package and install <a class="md-anchor" id="create-pip"></a>
+When building from source, you will still build a pip package and install that.
 
 ```bash
 $ bazel build -c opt //tensorflow/tools/pip_package:build_pip_package
@@ -343,20 +519,43 @@ $ bazel build -c opt --config=cuda //tensorflow/tools/pip_package:build_pip_pack
 $ bazel-bin/tensorflow/tools/pip_package/build_pip_package /tmp/tensorflow_pkg
 
 # The name of the .whl file will depend on your platform.
-$ pip install /tmp/tensorflow_pkg/tensorflow-0.5.0-cp27-none-linux_x86_64.whl
+$ pip install /tmp/tensorflow_pkg/tensorflow-0.7.1-py2-none-linux_x86_64.whl
 ```
 
-## Train your first TensorFlow neural net model <a class="md-anchor" id="AUTOGENERATED-train-your-first-tensorflow-neural-net-model"></a>
+## Setting up TensorFlow for Development
+
+If you're working on TensorFlow itself, it is useful to be able to test your
+changes in an interactive python shell without having to reinstall TensorFlow.
+
+To set up TensorFlow such that all files are linked (instead of copied) from the
+system directories, run the following commands inside the TensorFlow root
+directory:
+
+```bash
+bazel build -c opt //tensorflow/tools/pip_package:build_pip_package
+mkdir _python_build
+cd _python_build
+ln -s ../bazel-bin/tensorflow/tools/pip_package/build_pip_package.runfiles/* .
+ln -s ../tensorflow/tools/pip_package/* .
+python setup.py develop
+```
+
+Note that this setup still requires you to rebuild the
+`//tensorflow/tools/pip_package:build_pip_package` target every time you change
+a C++ file; add, delete, or move any python file; or if you change bazel build
+rules.
+
+## Train your first TensorFlow neural net model
 
 Starting from the root of your source tree, run:
 
 ```python
 $ cd tensorflow/models/image/mnist
 $ python convolutional.py
-Succesfully downloaded train-images-idx3-ubyte.gz 9912422 bytes.
-Succesfully downloaded train-labels-idx1-ubyte.gz 28881 bytes.
-Succesfully downloaded t10k-images-idx3-ubyte.gz 1648877 bytes.
-Succesfully downloaded t10k-labels-idx1-ubyte.gz 4542 bytes.
+Successfully downloaded train-images-idx3-ubyte.gz 9912422 bytes.
+Successfully downloaded train-labels-idx1-ubyte.gz 28881 bytes.
+Successfully downloaded t10k-images-idx3-ubyte.gz 1648877 bytes.
+Successfully downloaded t10k-labels-idx1-ubyte.gz 4542 bytes.
 Extracting data/train-images-idx3-ubyte.gz
 Extracting data/train-labels-idx1-ubyte.gz
 Extracting data/t10k-images-idx3-ubyte.gz
@@ -374,9 +573,9 @@ Validation error: 7.0%
 ...
 ```
 
-## Common Problems <a class="md-anchor" id="common_install_problems"></a>
+## Common Problems
 
-### GPU-related issues <a class="md-anchor" id="AUTOGENERATED-gpu-related-issues"></a>
+### GPU-related issues
 
 If you encounter the following when trying to run a TensorFlow program:
 
@@ -384,11 +583,26 @@ If you encounter the following when trying to run a TensorFlow program:
 ImportError: libcudart.so.7.0: cannot open shared object file: No such file or directory
 ```
 
-Make sure you followed the the GPU installation [instructions](#install_cuda).
+Make sure you followed the GPU installation [instructions](#optional-install-cuda-gpus-on-linux).
+If you built from source, and you left the Cuda or cuDNN version empty, try specifying them
+explicitly.
 
-### Pip installation issues <a class="md-anchor" id="AUTOGENERATED-pip-installation-issues"></a>
+### Pip installation issues
 
-#### Can't find setup.py <a class="md-anchor" id="AUTOGENERATED-can-t-find-setup.py"></a>
+#### Cannot import name 'descriptor'
+
+```python
+ImportError: Traceback (most recent call last):
+  File "/usr/local/lib/python3.4/dist-packages/tensorflow/core/framework/graph_pb2.py", line 6, in <module>
+    from google.protobuf import descriptor as _descriptor
+ImportError: cannot import name 'descriptor'
+```
+
+If you the above error when upgrading to a newer version of TensorFlow, try
+uninstalling both TensorFlow and protobuf (if installed) and re-installing
+TensorFlow (which will also install the correct protobuf dependency).
+
+#### Can't find setup.py
 
 If, during `pip install`, you encounter an error like:
 
@@ -397,15 +611,15 @@ If, during `pip install`, you encounter an error like:
 IOError: [Errno 2] No such file or directory: '/tmp/pip-o6Tpui-build/setup.py'
 ```
 
-Solution: upgrade your version of `pip`:
+Solution: upgrade your version of pip:
 
 ```bash
 pip install --upgrade pip
 ```
 
-This may require `sudo`, depending on how `pip` is installed.
+This may require `sudo`, depending on how pip is installed.
 
-#### SSLError: SSL_VERIFY_FAILED <a class="md-anchor" id="AUTOGENERATED-sslerror--ssl_verify_failed"></a>
+#### SSLError: SSL_VERIFY_FAILED
 
 If, during pip install from a URL, you encounter an error like:
 
@@ -416,7 +630,7 @@ SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
 
 Solution: Download the wheel manually via curl or wget, and pip install locally.
 
-### On Linux <a class="md-anchor" id="AUTOGENERATED-on-linux"></a>
+### Linux issues
 
 If you encounter:
 
@@ -429,39 +643,48 @@ SyntaxError: invalid syntax
 
 Solution: make sure you are using Python 2.7.
 
-### On MacOSX <a class="md-anchor" id="AUTOGENERATED-on-macosx"></a>
-
+### Mac OS X: ImportError: No module named copyreg
 
-If you encounter:
+On Mac OS X, you may encounter the following when importing tensorflow.
 
 ```python
-import six.moves.copyreg as copyreg
-
+>>> import tensorflow as tf
+...
 ImportError: No module named copyreg
 ```
 
-Solution: TensorFlow depends on protobuf, which requires `six-1.10.0`. Apple's
-default python environment has `six-1.4.1` and may be difficult to upgrade.
-There are several ways to fix this:
+Solution: TensorFlow depends on protobuf, which requires the Python package
+`six-1.10.0`. Apple's default Python installation only provides `six-1.4.1`.
 
-1. Upgrade the system-wide copy of `six`:
+You can resolve the issue in one of the following ways:
 
-    ```bash
-    sudo easy_install -U six
-    ```
+* Upgrade the Python installation with the current version of `six`:
 
-2. Install a separate copy of python via homebrew:
+```bash
+$ sudo easy_install -U six
+```
 
-    ```bash
-    brew install python
-    ```
+* Install TensorFlow with a separate Python library:
 
-3. Build or use TensorFlow
-   [within `virtualenv`](#virtualenv_install).
+    *  Using [Virtualenv](#virtualenv-installation).
+    *  Using [Docker](#docker-installation).
 
+* Install a separate copy of Python via [Homebrew](http://brew.sh/) or
+[MacPorts](https://www.macports.org/) and re-install TensorFlow in that
+copy of Python.
 
+### Mac OS X: OSError: [Errno 1] Operation not permitted:
 
-If you encounter:
+On El Capitan, "six" is a special package that can't be modified, and this
+error is reported when "pip install" tried to modify this package. To fix use
+"ignore_installed" flag, ie
+
+sudo pip install --ignore-installed six https://storage.googleapis.com/....
+
+
+### Mac OS X: TypeError: `__init__()` got an unexpected keyword argument 'syntax'
+
+On Mac OS X, you may encounter the following when importing tensorflow.
 
 ```
 >>> import tensorflow as tf
@@ -482,5 +705,5 @@ The best current solution is to make sure older versions of protobuf are not
 installed, such as:
 
 ```bash
-brew reinstall --devel protobuf
-```
+$ pip install --upgrade protobuf
+```