diff --git a/docs/source/config/overview.txt b/docs/source/config/overview.txt
index 0860f13..a0f6a0b 100644
--- a/docs/source/config/overview.txt
+++ b/docs/source/config/overview.txt
@@ -286,6 +286,8 @@ following algorithm:
 * If not, the value returned by :func:`IPython.utils.path.get_ipython_dir`
   is used. This function will first look at the :envvar:`IPYTHONDIR`
   environment variable and then default to a platform-specific default.
+  Historical support for the :envvar:`IPYTHON_DIR` environment variable will
+  be removed in a future release.
 
 On posix systems (Linux, Unix, etc.), IPython respects the ``$XDG_CONFIG_HOME``
 part of the `XDG Base Directory`_ specification. If ``$XDG_CONFIG_HOME`` is
diff --git a/docs/source/whatsnew/development.txt b/docs/source/whatsnew/development.txt
index 1023655..a650907 100644
--- a/docs/source/whatsnew/development.txt
+++ b/docs/source/whatsnew/development.txt
@@ -15,4 +15,7 @@ Other new features
 * **%install_ext**: A new magic function to install an IPython extension from
   a URL. E.g. ``%install_ext https://bitbucket.org/birkenfeld/ipython-physics/raw/d1310a2ab15d/physics.py``.
 
+* The :envvar:`IPYTHON_DIR` environment variable has been deprecated and
+  support for it will be removed in a future release. Please use the
+  :envvar:`IPYTHONDIR` environment variable instead.