Debian Codegraph @

docs/howto/upgrade-version.txt

raw
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.