Debian Codegraph @

docs/howto/windows.txt

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