DOC Instructions to troubleshoot Windows path length limit (scikit-learn#15916)

ogrisel · ogrisel · commit ce49cb48f87f · 2020-01-02T10:43:42.000+01:00
diff --git a/doc/install.rst b/doc/install.rst
@@ -126,7 +126,7 @@ If you have not installed NumPy or SciPy yet, you can also install these using
 conda or pip. When using pip, please ensure that *binary wheels* are used,
 and NumPy and SciPy are not recompiled from source, which can happen when using
 particular configurations of operating system and hardware (such as Linux on
-a Raspberry Pi). 
+a Raspberry Pi).
 
 If you must install scikit-learn and its dependencies with pip, you can install
 it as ``scikit-learn[alldeps]``.
@@ -255,3 +255,38 @@ WinPython for Windows
 
 The `WinPython <https://winpython.github.io/>`_ project distributes
 scikit-learn as an additional plugin.
+
+
+Troubleshooting
+===============
+
+.. _windows_longpath:
+
+Error caused by file path length limit on Windows
+-------------------------------------------------
+
+It can happen that pip fails to install packages when reaching the default path
+size limit of Windows if Python is installed in a nested location such as the
+`AppData` folder structure under the user home directory, for instance::
+
+    C:\Users\username>C:\Users\username\AppData\Local\Microsoft\WindowsApps\python.exe -m pip install scikit-learn
+    Collecting scikit-learn
+    ...
+    Installing collected packages: scikit-learn
+    ERROR: Could not install packages due to an EnvironmentError: [Errno 2] No such file or directory: 'C:\\Users\\username\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.7_qbz5n2kfra8p0\\LocalCache\\local-packages\\Python37\\site-packages\\sklearn\\datasets\\tests\\data\\openml\\292\\api-v1-json-data-list-data_name-australian-limit-2-data_version-1-status-deactivated.json.gz'
+
+In this case it is possible to lift that limit in the Windows registry by
+using the ``regedit`` tool:
+
+#. Type "regedit" in the Windows start menu to launch ``regedit``.
+
+#. Go to the
+   ``Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem``
+   key.
+
+#. Edit the value of the ``LongPathsEnabled`` property of that key and set
+   it to 1.
+
+#. Reinstall scikit-learn (ignoring the previous broken installation)::
+
+       pip install --exists-action=i scikit-learn
