Fixed #19934 - Use of Pillow is now preferred over PIL.

This starts the deprecation period for PIL (support to end in 1.8).

4 files changed, 21 insertions, 6 deletions

diff --git a/docs/faq/contributing.txt b/docs/faq/contributing.txt
index 6f2dfd906f..20950e88c5 100644
--- a/docs/faq/contributing.txt
+++ b/docs/faq/contributing.txt
@@ -27,7 +27,7 @@ to make it dead easy, even for someone who may not be intimately familiar with
 that area of the code, to understand the problem and verify the fix:
 
 * Are there clear instructions on how to reproduce the bug? If this
-  touches a dependency (such as PIL), a contrib module, or a specific
+  touches a dependency (such as Pillow/PIL), a contrib module, or a specific
   database, are those instructions clear enough even for someone not
   familiar with it?
 
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 862907b2a8..774de2a2fd 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -365,6 +365,12 @@ these changes.
 * ``django.conf.urls.shortcut`` and ``django.views.defaults.shortcut`` will be
   removed.
 
+* Support for the Python Imaging Library (PIL) module will be removed, as it
+  no longer appears to be actively maintained & does not work on Python 3.
+  You are advised to install `Pillow`_, which should be used instead.
+
+.. _`Pillow`: https://pypi.python.org/pypi/Pillow
+
 * The following private APIs will be removed:
 
   - ``django.db.close_connection()``
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index 29f889445d..054f45c430 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -608,19 +608,21 @@ For each field, we describe the default widget used if you don't specify
     * Normalizes to: An ``UploadedFile`` object that wraps the file content
       and file name into a single object.
     * Validates that file data has been bound to the form, and that the
-      file is of an image format understood by PIL.
+      file is of an image format understood by Pillow/PIL.
     * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``,
       ``invalid_image``
 
-    Using an ``ImageField`` requires that the `Python Imaging Library`_ (PIL)
-    is installed and supports the image formats you use. If you encounter a
-    ``corrupt image`` error when you upload an image, it usually means PIL
+    Using an ``ImageField`` requires that either `Pillow`_ (recommended) or the
+    `Python Imaging Library`_ (PIL) are installed and supports the image
+    formats you use. If you encounter a ``corrupt image`` error when you
+    upload an image, it usually means either Pillow or PIL
     doesn't understand its format. To fix this, install the appropriate
-    library and reinstall PIL.
+    library and reinstall Pillow or PIL.
 
     When you use an ``ImageField`` on a form, you must also remember to
     :ref:`bind the file data to the form <binding-uploaded-files>`.
 
+.. _Pillow: http://python-imaging.github.io/Pillow/
 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
 
 ``IntegerField``
diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt
index 5780229eb5..7469783659 100644
--- a/docs/releases/1.6.txt
+++ b/docs/releases/1.6.txt
@@ -220,6 +220,13 @@ Minor features
 * Added ``BCryptSHA256PasswordHasher`` to resolve the password truncation issue
   with bcrypt.
 
+* `Pillow`_ is now the preferred image manipulation library to use with Django.
+  `PIL`_ is pending deprecation (support to be removed in Django 1.8).
+  To upgrade, you should **first** uninstall PIL, **then** install Pillow.
+
+.. _`Pillow`: https://pypi.python.org/pypi/Pillow
+.. _`PIL`: https://pypi.python.org/pypi/PIL
+
 Backwards incompatible changes in 1.6
 =====================================