Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #18115 - added warning about overlaid install.

Setup.py now warns if it detects that Django is being installed over top
of a previous installation that was never removed. This should only
happen when installing with ``python setup.py install``, as pip
automatically uninstalls before installing a new version and
easy_install installs as an egg directory.

Also generally updated the installation doc.
  • Loading branch information...
commit 6ed7d40727f70934df6ab0ac96f5f1c4f01c534f 1 parent 23b9418
Carl Meyer authored
138  docs/topics/install.txt
@@ -154,34 +154,19 @@ If you are upgrading your installation of Django from a previous version,
154 154
 you will need to uninstall the old Django version before installing the
155 155
 new version.
156 156
 
157  
-If you installed Django using ``setup.py install``, uninstalling
158  
-is as simple as deleting the ``django`` directory from your Python
159  
-``site-packages``.
  157
+If you installed Django using pip_ or ``easy_install`` previously, installing
  158
+with pip_ or ``easy_install`` again will automatically take care of the old
  159
+version, so you don't need to do it yourself.
160 160
 
161  
-If you installed Django from a Python egg, remove the Django ``.egg`` file,
162  
-and remove the reference to the egg in the file named ``easy-install.pth``.
163  
-This file should also be located in your ``site-packages`` directory.
  161
+If you previously installed Django using ``python setup.py install``,
  162
+uninstalling is as simple as deleting the ``django`` directory from your Python
  163
+``site-packages``. To find the directory you need to remove, you can run the
  164
+following at your shell prompt (not the interactive Python prompt):
164 165
 
165  
-.. _finding-site-packages:
  166
+.. code-block:: bash
166 167
 
167  
-.. admonition:: Where are my ``site-packages`` stored?
  168
+    python -c "import sys; sys.path = sys.path[1:]; import django; print django.__path__"
168 169
 
169  
-    The location of the ``site-packages`` directory depends on the operating
170  
-    system, and the location in which Python was installed. To find out your
171  
-    system's ``site-packages`` location, execute the following:
172  
-
173  
-    .. code-block:: bash
174  
-
175  
-        python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
176  
-
177  
-    (Note that this should be run from a shell prompt, not a Python interactive
178  
-    prompt.)
179  
-
180  
-    Some Debian-based Linux distributions have separate ``site-packages``
181  
-    directories for user-installed packages, such as when installing Django
182  
-    from a downloaded tarball. The command  listed above will give you the
183  
-    system's ``site-packages``, the user's directory can be found in
184  
-    ``/usr/local/lib/`` instead of ``/usr/lib/``.
185 170
 
186 171
 .. _install-django-code:
187 172
 
@@ -253,6 +238,15 @@ Installing an official release manually
253 238
    run the command ``python setup.py install``. This will install Django in
254 239
    your Python installation's ``site-packages`` directory.
255 240
 
  241
+   .. admonition:: Removing an old version
  242
+
  243
+       If you use this installation technique, it is particularly important
  244
+       that you :ref:`remove any existing
  245
+       installations<removing-old-versions-of-django>` of Django
  246
+       first. Otherwise, you can end up with a broken installation that
  247
+       includes files from previous versions that have since been removed from
  248
+       Django.
  249
+
256 250
 .. _download page: https://www.djangoproject.com/download/
257 251
 .. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
258 252
 .. _7-zip: http://www.7-zip.org/
@@ -291,44 +285,26 @@ latest bug fixes and improvements, follow these instructions:
291 285
 
292 286
    This will create a directory ``django-trunk`` in your current directory.
293 287
 
294  
-3. Next, make sure that the Python interpreter can load Django's code. The most
295  
-   convenient way to do this is to `modify Python's search path`_. Add a ``.pth``
296  
-   file containing the full path to the ``django-trunk`` directory to your
297  
-   system's ``site-packages`` directory. For example, on a Unix-like system:
  288
+3. Make sure that the Python interpreter can load Django's code. The most
  289
+   convenient way to do this is via pip_. Run the following command:
298 290
 
299 291
    .. code-block:: bash
300 292
 
301  
-       echo WORKING-DIR/django-trunk > SITE-PACKAGES-DIR/django.pth
  293
+       sudo pip install -e django-trunk/
302 294
 
303  
-   (In the above line, change ``SITE-PACKAGES-DIR`` to match the location of
304  
-   your system's ``site-packages`` directory, as explained in the
305  
-   :ref:`Where are my site-packages stored? <finding-site-packages>` section
306  
-   above. Change ``WORKING-DIR/django-trunk`` to match the full path to your
307  
-   new ``django-trunk`` directory.)
  295
+   (If using a virtualenv_ you can omit ``sudo``.)
308 296
 
309  
-4. On Unix-like systems, create a symbolic link to the file
310  
-   ``django-trunk/django/bin/django-admin.py`` in a directory on your system
311  
-   path, such as ``/usr/local/bin``. For example:
312  
-
313  
-   .. code-block:: bash
  297
+   This will make Django's code importable, and will also make the
  298
+   ``django-admin.py`` utility command available. In other words, you're all
  299
+   set!
314 300
 
315  
-       ln -s WORKING-DIR/django-trunk/django/bin/django-admin.py /usr/local/bin/
316  
-
317  
-   (In the above line, change WORKING-DIR to match the full path to your new
318  
-   ``django-trunk`` directory.)
319  
-
320  
-   This simply lets you type ``django-admin.py`` from within any directory,
321  
-   rather than having to qualify the command with the full path to the file.
322  
-
323  
-   On Windows systems, the same result can be achieved by copying the file
324  
-   ``django-trunk/django/bin/django-admin.py`` to somewhere on your system
325  
-   path, for example ``C:\Python27\Scripts``.
  301
+   If you don't have pip_ available, see the alternative instructions for
  302
+   `installing the development version without pip`_.
326 303
 
327 304
 .. warning::
328 305
 
329 306
     Don't run ``sudo python setup.py install``, because you've already
330  
-    carried out the equivalent actions in steps 3 and 4. Furthermore, this is
331  
-    known to cause problems when updating to a more recent version of Django.
  307
+    carried out the equivalent actions in step 3.
332 308
 
333 309
 When you want to update your copy of the Django source code, just run the
334 310
 command ``git pull`` from within the ``django-trunk`` directory. When you do
@@ -336,3 +312,61 @@ this, Git will automatically download any changes.
336 312
 
337 313
 .. _Git: http://git-scm.com/
338 314
 .. _`modify Python's search path`: http://docs.python.org/install/index.html#modifying-python-s-search-path
  315
+.. _installing-the-development-version-without-pip:
  316
+
  317
+Installing the development version without pip
  318
+----------------------------------------------
  319
+
  320
+If you don't have pip_, you can instead manually `modify Python's search
  321
+path`_.
  322
+
  323
+First follow steps 1 and 2 above, so that you have a ``django-trunk`` directory
  324
+with a checkout of Django's latest code in it. Then add a ``.pth`` file
  325
+containing the full path to the ``django-trunk`` directory to your system's
  326
+``site-packages`` directory. For example, on a Unix-like system:
  327
+
  328
+.. code-block:: bash
  329
+
  330
+    echo WORKING-DIR/django-trunk > SITE-PACKAGES-DIR/django.pth
  331
+
  332
+In the above line, change ``WORKING-DIR/django-trunk`` to match the full path
  333
+to your new ``django-trunk`` directory, and change ``SITE-PACKAGES-DIR`` to
  334
+match the location of your system's ``site-packages`` directory.
  335
+
  336
+The location of the ``site-packages`` directory depends on the operating
  337
+system, and the location in which Python was installed. To find your system's
  338
+``site-packages`` location, execute the following:
  339
+
  340
+.. code-block:: bash
  341
+
  342
+    python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"
  343
+
  344
+(Note that this should be run from a shell prompt, not a Python interactive
  345
+prompt.)
  346
+
  347
+Some Debian-based Linux distributions have separate ``site-packages``
  348
+directories for user-installed packages, such as when installing Django from
  349
+a downloaded tarball. The command listed above will give you the system's
  350
+``site-packages``, the user's directory can be found in ``/usr/local/lib/``
  351
+instead of ``/usr/lib/``.
  352
+
  353
+Next you need to make the ``django-admin.py`` utility available in your
  354
+shell PATH.
  355
+
  356
+On Unix-like systems, create a symbolic link to the file
  357
+``django-trunk/django/bin/django-admin.py`` in a directory on your system
  358
+path, such as ``/usr/local/bin``. For example:
  359
+
  360
+.. code-block:: bash
  361
+
  362
+    ln -s WORKING-DIR/django-trunk/django/bin/django-admin.py /usr/local/bin/
  363
+
  364
+(In the above line, change WORKING-DIR to match the full path to your new
  365
+``django-trunk`` directory.)
  366
+
  367
+This simply lets you type ``django-admin.py`` from within any directory,
  368
+rather than having to qualify the command with the full path to the file.
  369
+
  370
+On Windows systems, the same result can be achieved by copying the file
  371
+``django-trunk/django/bin/django-admin.py`` to somewhere on your system
  372
+path, for example ``C:\Python27\Scripts``.
36  setup.py
... ...
@@ -1,9 +1,25 @@
1 1
 from distutils.core import setup
2 2
 from distutils.command.install_data import install_data
3 3
 from distutils.command.install import INSTALL_SCHEMES
  4
+from distutils.sysconfig import get_python_lib
4 5
 import os
5 6
 import sys
6 7
 
  8
+# Warn if we are installing over top of an existing installation. This can
  9
+# cause issues where files that were deleted from a more recent Django are
  10
+# still present in site-packages. See #18115.
  11
+overlay_warning = False
  12
+if "install" in sys.argv:
  13
+    # We have to try also with an explicit prefix of /usr/local in order to
  14
+    # catch Debian's custom user site-packages directory.
  15
+    for lib_path in get_python_lib(), get_python_lib(prefix="/usr/local"):
  16
+        existing_path = os.path.abspath(os.path.join(lib_path, "django"))
  17
+        if os.path.exists(existing_path):
  18
+            # We note the need for the warning here, but present it after the
  19
+            # command is run, so it's more likely to be seen.
  20
+            overlay_warning = True
  21
+            break
  22
+
7 23
 class osx_install_data(install_data):
8 24
     # On MacOS, the platform-specific lib dir is /System/Library/Framework/Python/.../
9 25
     # which is wrong. Python 2.5 supplied with MacOS 10.5 has an Apple-specific fix
@@ -97,3 +113,23 @@ def fullsplit(path, result=None):
97 113
         'Topic :: Software Development :: Libraries :: Python Modules',
98 114
    ],
99 115
 )
  116
+
  117
+if overlay_warning:
  118
+    sys.stderr.write("""
  119
+
  120
+========
  121
+WARNING!
  122
+========
  123
+
  124
+You have just installed Django over top of an existing
  125
+installation, without removing it first. Because of this,
  126
+your install may now include extraneous files from a
  127
+previous version that have since been removed from
  128
+Django. This is known to cause a variety of problems. You
  129
+should manually remove the
  130
+
  131
+%(existing_path)s
  132
+
  133
+directory and re-install Django.
  134
+
  135
+""" % { "existing_path": existing_path })

0 notes on commit 6ed7d40

Please sign in to comment.
Something went wrong with that request. Please try again.