| 1 |
======================================== |
| 2 |
How to upgrade Django to a newer version |
| 3 |
======================================== |
| 4 |
|
| 5 |
While it can be a complex process at times, upgrading to the latest Django |
| 6 |
version has several benefits: |
| 7 |
|
| 8 |
* New features and improvements are added. |
| 9 |
* Bugs are fixed. |
| 10 |
* Older version of Django will eventually no longer receive security updates. |
| 11 |
(see :ref:`supported-versions-policy`). |
| 12 |
* Upgrading as each new Django release is available makes future upgrades less |
| 13 |
painful by keeping your code base up to date. |
| 14 |
|
| 15 |
.. admonition:: Tools to help with version upgrades |
| 16 |
|
| 17 |
Django has a vibrant ecosystem. There are automated upgrade helpers |
| 18 |
highlighted on the `Community Ecosystem |
| 19 |
<https://www.djangoproject.com/community/ecosystem/#upgrade-utilities>`__ |
| 20 |
page. |
| 21 |
|
| 22 |
Here are some things to consider to help make your upgrade process as smooth as |
| 23 |
possible. |
| 24 |
|
| 25 |
Required Reading |
| 26 |
================ |
| 27 |
|
| 28 |
If it's your first time doing an upgrade, it is useful to read the :doc:`guide |
| 29 |
on the different release processes </internals/release-process>`. |
| 30 |
|
| 31 |
Afterward, you should familiarize yourself with the changes that were made in |
| 32 |
the new Django version(s): |
| 33 |
|
| 34 |
* Read the :doc:`release notes </releases/index>` for each 'final' release from |
| 35 |
the one after your current Django version, up to and including the version to |
| 36 |
which you plan to upgrade. |
| 37 |
* Look at the :doc:`deprecation timeline</internals/deprecation>` for the |
| 38 |
relevant versions. |
| 39 |
|
| 40 |
Pay particular attention to backwards incompatible changes to get a clear idea |
| 41 |
of what will be needed for a successful upgrade. |
| 42 |
|
| 43 |
If you're upgrading through more than one feature version (e.g. 2.0 to 2.2), |
| 44 |
it's usually easier to upgrade through each feature release incrementally |
| 45 |
(2.0 to 2.1 to 2.2) rather than to make all the changes for each feature |
| 46 |
release at once. For each feature release, use the latest patch release (e.g. |
| 47 |
for 2.1, use 2.1.15). |
| 48 |
|
| 49 |
The same incremental upgrade approach is recommended when upgrading from one |
| 50 |
LTS to the next. |
| 51 |
|
| 52 |
Dependencies |
| 53 |
============ |
| 54 |
|
| 55 |
In most cases it will be necessary to upgrade to the latest version of your |
| 56 |
Django-related dependencies as well. If the Django version was recently |
| 57 |
released or if some of your dependencies are not well-maintained, some of your |
| 58 |
dependencies may not yet support the new Django version. In these cases you may |
| 59 |
have to wait until new versions of your dependencies are released. |
| 60 |
|
| 61 |
Resolving deprecation warnings |
| 62 |
============================== |
| 63 |
|
| 64 |
Before upgrading, it's a good idea to resolve any deprecation warnings raised |
| 65 |
by your project while using your current version of Django. Fixing these |
| 66 |
warnings before upgrading ensures that you're informed about areas of the code |
| 67 |
that need altering. |
| 68 |
|
| 69 |
In Python, deprecation warnings are silenced by default. You must turn them on |
| 70 |
using the ``-Wa`` Python command line option or the :envvar:`PYTHONWARNINGS` |
| 71 |
environment variable. For example, to show warnings while running tests: |
| 72 |
|
| 73 |
.. console:: |
| 74 |
|
| 75 |
$ python -Wa manage.py test |
| 76 |
|
| 77 |
If you're not using the Django test runner, you may need to also ensure that |
| 78 |
any console output is not captured which would hide deprecation warnings. For |
| 79 |
example, if you use `pytest <https://docs.pytest.org/>`__: |
| 80 |
|
| 81 |
.. code-block:: console |
| 82 |
|
| 83 |
$ PYTHONWARNINGS=always pytest tests --capture=no |
| 84 |
|
| 85 |
Resolve any deprecation warnings with your current version of Django before |
| 86 |
continuing the upgrade process. |
| 87 |
|
| 88 |
Third party applications might use deprecated APIs in order to support multiple |
| 89 |
versions of Django, so deprecation warnings in packages you've installed don't |
| 90 |
necessarily indicate a problem. If a package doesn't support the latest version |
| 91 |
of Django, consider raising an issue or sending a pull request for it. |
| 92 |
|
| 93 |
Installation |
| 94 |
============ |
| 95 |
|
| 96 |
Once you're ready, it is time to :doc:`install the new Django version |
| 97 |
</topics/install>`. If you are using a :mod:`virtual environment <venv>` and it |
| 98 |
is a major upgrade, you might want to set up a new environment with all the |
| 99 |
dependencies first. |
| 100 |
|
| 101 |
If you installed Django with pip_, you can use the ``--upgrade`` or ``-U`` flag: |
| 102 |
|
| 103 |
.. console:: |
| 104 |
|
| 105 |
$ python -m pip install -U Django |
| 106 |
|
| 107 |
.. _pip: https://pip.pypa.io/ |
| 108 |
|
| 109 |
Testing |
| 110 |
======= |
| 111 |
|
| 112 |
When the new environment is set up, :doc:`run the full test suite |
| 113 |
</topics/testing/overview>` for your application. Again, it's useful to turn |
| 114 |
on deprecation warnings on so they're shown in the test output (you can also |
| 115 |
use the flag if you test your app manually using ``manage.py runserver``): |
| 116 |
|
| 117 |
.. console:: |
| 118 |
|
| 119 |
$ python -Wa manage.py test |
| 120 |
|
| 121 |
After you have run the tests, fix any failures. While you have the release |
| 122 |
notes fresh in your mind, it may also be a good time to take advantage of new |
| 123 |
features in Django by refactoring your code to eliminate any deprecation |
| 124 |
warnings. |
| 125 |
|
| 126 |
Deployment |
| 127 |
========== |
| 128 |
|
| 129 |
When you are sufficiently confident your app works with the new version of |
| 130 |
Django, you're ready to go ahead and :doc:`deploy </howto/deployment/index>` |
| 131 |
your upgraded Django project. |
| 132 |
|
| 133 |
If you are using caching provided by Django, you should consider clearing your |
| 134 |
cache after upgrading. Otherwise you may run into problems, for example, if you |
| 135 |
are caching pickled objects as these objects are not guaranteed to be |
| 136 |
pickle-compatible across Django versions. A past instance of incompatibility |
| 137 |
was caching pickled :class:`~django.http.HttpResponse` objects, either |
| 138 |
directly or indirectly via the :func:`~django.views.decorators.cache.cache_page` |
| 139 |
decorator. |