| 1 |
================================ |
| 2 |
How to install Django on Windows |
| 3 |
================================ |
| 4 |
|
| 5 |
This document will guide you through installing Python 3.14 and Django on |
| 6 |
Windows. It also provides instructions for setting up a virtual environment, |
| 7 |
which makes it easier to work on Python projects. This is meant as a beginner's |
| 8 |
guide for users working on Django projects and does not reflect how Django |
| 9 |
should be installed when developing changes for Django itself. |
| 10 |
|
| 11 |
The steps in this guide have been tested with Windows 10. In other |
| 12 |
versions, the steps would be similar. You will need to be familiar with using |
| 13 |
the Windows command prompt. |
| 14 |
|
| 15 |
.. _install_python_windows: |
| 16 |
|
| 17 |
Install Python |
| 18 |
============== |
| 19 |
|
| 20 |
Django is a Python web framework, thus requiring Python to be installed on your |
| 21 |
machine. At the time of writing, Python 3.14 is the latest version. |
| 22 |
|
| 23 |
To install Python on your machine go to https://www.python.org/downloads/. The |
| 24 |
website should offer you a download button for the latest Python version. |
| 25 |
Download the executable installer and run it. Check the boxes next to "Install |
| 26 |
launcher for all users (recommended)" then click "Install Now". |
| 27 |
|
| 28 |
After installation, open the command prompt and check that the Python version |
| 29 |
matches the version you installed by executing: |
| 30 |
|
| 31 |
.. code-block:: doscon |
| 32 |
|
| 33 |
...\> py --version |
| 34 |
|
| 35 |
.. admonition:: ``py`` is not recognized or found |
| 36 |
|
| 37 |
Depending on how you've installed Python (such as via the Microsoft Store), |
| 38 |
``py`` may not be available in the command prompt. |
| 39 |
|
| 40 |
You will then need to use ``python`` instead of ``py`` when entering |
| 41 |
commands. |
| 42 |
|
| 43 |
.. seealso:: |
| 44 |
|
| 45 |
For more details, see :doc:`python:using/windows` documentation. |
| 46 |
|
| 47 |
About ``pip`` |
| 48 |
============= |
| 49 |
|
| 50 |
:pypi:`pip` is a package manager for Python and is included by default with the |
| 51 |
Python installer. It helps to install and uninstall Python packages |
| 52 |
(such as Django!). For the rest of the installation, we'll use ``pip`` to |
| 53 |
install Python packages from the command line. |
| 54 |
|
| 55 |
.. _virtualenvironment: |
| 56 |
|
| 57 |
Setting up a virtual environment |
| 58 |
================================ |
| 59 |
|
| 60 |
It is best practice to provide a dedicated environment for each Django project |
| 61 |
you create. There are many options to manage environments and packages within |
| 62 |
the Python ecosystem, some of which are recommended in the `Python |
| 63 |
documentation <https://packaging.python.org/guides/tool-recommendations/>`_. |
| 64 |
Python itself comes with :doc:`venv <python:tutorial/venv>` for managing |
| 65 |
environments which we will use for this guide. |
| 66 |
|
| 67 |
To create a virtual environment for your project, open a new command prompt, |
| 68 |
navigate to the folder where you want to create your project and then enter the |
| 69 |
following: |
| 70 |
|
| 71 |
.. code-block:: doscon |
| 72 |
|
| 73 |
...\> py -m venv project-name |
| 74 |
|
| 75 |
This will create a folder called 'project-name' if it does not already exist |
| 76 |
and set up the virtual environment. To activate the environment, run: |
| 77 |
|
| 78 |
.. code-block:: doscon |
| 79 |
|
| 80 |
...\> project-name\Scripts\activate.bat |
| 81 |
|
| 82 |
The virtual environment will be activated and you'll see "(project-name)" next |
| 83 |
to the command prompt to designate that. Each time you start a new command |
| 84 |
prompt, you'll need to activate the environment again. |
| 85 |
|
| 86 |
Install Django |
| 87 |
============== |
| 88 |
|
| 89 |
Django can be installed easily using ``pip`` within your virtual environment. |
| 90 |
|
| 91 |
In the command prompt, ensure your virtual environment is active, and execute |
| 92 |
the following command: |
| 93 |
|
| 94 |
.. code-block:: doscon |
| 95 |
|
| 96 |
...\> py -m pip install Django |
| 97 |
|
| 98 |
This will download and install the latest Django release. |
| 99 |
|
| 100 |
After the installation has completed, you can verify your Django installation |
| 101 |
by executing ``django-admin --version`` in the command prompt. |
| 102 |
|
| 103 |
See :ref:`database-installation` for information on database installation |
| 104 |
with Django. |
| 105 |
|
| 106 |
Colored terminal output |
| 107 |
======================= |
| 108 |
|
| 109 |
A quality-of-life feature adds colored (rather than monochrome) output to the |
| 110 |
terminal. In modern terminals this should work for both CMD and PowerShell. If |
| 111 |
for some reason this needs to be disabled, set the environmental variable |
| 112 |
:envvar:`DJANGO_COLORS` to ``nocolor``. |
| 113 |
|
| 114 |
On older Windows versions, or legacy terminals, :pypi:`colorama` 0.4.6+ must be |
| 115 |
installed to enable syntax coloring: |
| 116 |
|
| 117 |
.. code-block:: doscon |
| 118 |
|
| 119 |
...\> py -m pip install "colorama >= 0.4.6" |
| 120 |
|
| 121 |
See :ref:`syntax-coloring` for more information on color settings. |
| 122 |
|
| 123 |
Common pitfalls |
| 124 |
=============== |
| 125 |
|
| 126 |
* If ``django-admin`` only displays the help text no matter what arguments |
| 127 |
it is given, there is probably a problem with the file association in |
| 128 |
Windows. Check if there is more than one environment variable set for |
| 129 |
running Python scripts in ``PATH``. This usually occurs when there is more |
| 130 |
than one Python version installed. |
| 131 |
|
| 132 |
* If you are connecting to the internet behind a proxy, there might be problems |
| 133 |
in running the command ``py -m pip install Django``. Set the environment |
| 134 |
variables for proxy configuration in the command prompt as follows: |
| 135 |
|
| 136 |
.. code-block:: doscon |
| 137 |
|
| 138 |
...\> set http_proxy=http://username:password@proxyserver:proxyport |
| 139 |
...\> set https_proxy=https://username:password@proxyserver:proxyport |
| 140 |
|
| 141 |
* In general, Django assumes that ``UTF-8`` encoding is used for I/O. This may |
| 142 |
cause problems if your system is set to use a different encoding. Recent |
| 143 |
versions of Python allow setting the :envvar:`PYTHONUTF8` environment |
| 144 |
variable in order to force a ``UTF-8`` encoding. Windows 10 also provides a |
| 145 |
system-wide setting by checking ``Use Unicode UTF-8 for worldwide language |
| 146 |
support`` in :menuselection:`Language --> Administrative Language Settings |
| 147 |
--> Change system locale` in system settings. |