Debian Codegraph @

docs/man/django-admin.1

raw
1 .\" Man page generated from reStructuredText.
2 .
3 .
4 .nr rst2man-indent-level 0
5 .
6 .de1 rstReportMargin
7 \\$1 \\n[an-margin]
8 level \\n[rst2man-indent-level]
9 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
10 -
11 \\n[rst2man-indent0]
12 \\n[rst2man-indent1]
13 \\n[rst2man-indent2]
14 ..
15 .de1 INDENT
16 .\" .rstReportMargin pre:
17 . RS \\$1
18 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
19 . nr rst2man-indent-level +1
20 .\" .rstReportMargin post:
21 ..
22 .de UNINDENT
23 . RE
24 .\" indent \\n[an-margin]
25 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
26 .nr rst2man-indent-level -1
27 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
28 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
29 ..
30 .TH "DJANGO-ADMIN" "1" "April 02, 2025" "5.2" "Django"
31 .SH NAME
32 django-admin \- Utility script for the Django web framework
33 .sp
34 \fBdjango\-admin\fP is Django\(aqs command\-line utility for administrative tasks.
35 This document outlines all it can do.
36 .sp
37 In addition, \fBmanage.py\fP is automatically created in each Django project. It
38 does the same thing as \fBdjango\-admin\fP but also sets the
39 \fI\%DJANGO_SETTINGS_MODULE\fP environment variable so that it points to your
40 project\(aqs \fBsettings.py\fP file.
41 .sp
42 The \fBdjango\-admin\fP script should be on your system path if you installed
43 Django via \fBpip\fP\&. If it\(aqs not in your path, ensure you have your virtual
44 environment activated.
45 .sp
46 Generally, when working on a single Django project, it\(aqs easier to use
47 \fBmanage.py\fP than \fBdjango\-admin\fP\&. If you need to switch between multiple
48 Django settings files, use \fBdjango\-admin\fP with
49 \fI\%DJANGO_SETTINGS_MODULE\fP or the \fI\%\-\-settings\fP command line
50 option.
51 .sp
52 The command\-line examples throughout this document use \fBdjango\-admin\fP to
53 be consistent, but any example can use \fBmanage.py\fP or \fBpython \-m django\fP
54 just as well.
55 .SH USAGE
56 .INDENT 0.0
57 .INDENT 3.5
58 .sp
59 .EX
60 $ django\-admin <command> [options]
61 $ manage.py <command> [options]
62 $ python \-m django <command> [options]
63 .EE
64 .UNINDENT
65 .UNINDENT
66 .sp
67 \fBcommand\fP should be one of the commands listed in this document.
68 \fBoptions\fP, which is optional, should be zero or more of the options available
69 for the given command.
70 .SS Getting runtime help
71 .INDENT 0.0
72 .TP
73 .B django\-admin help
74 .UNINDENT
75 .sp
76 Run \fBdjango\-admin help\fP to display usage information and a list of the
77 commands provided by each application.
78 .sp
79 Run \fBdjango\-admin help \-\-commands\fP to display a list of all available
80 commands.
81 .sp
82 Run \fBdjango\-admin help <command>\fP to display a description of the given
83 command and a list of its available options.
84 .SS App names
85 .sp
86 Many commands take a list of \(dqapp names.\(dq An \(dqapp name\(dq is the basename of
87 the package containing your models. For example, if your \fI\%INSTALLED_APPS\fP
88 contains the string \fB\(aqmysite.blog\(aq\fP, the app name is \fBblog\fP\&.
89 .SS Determining the version
90 .INDENT 0.0
91 .TP
92 .B django\-admin version
93 .UNINDENT
94 .sp
95 Run \fBdjango\-admin version\fP to display the current Django version.
96 .sp
97 The output follows the schema described in \X'tty: link https://peps.python.org/pep-0440/'\fI\%PEP 440\fP\X'tty: link':
98 .INDENT 0.0
99 .INDENT 3.5
100 .sp
101 .EX
102 1.4.dev17026
103 1.4a1
104 1.4
105 .EE
106 .UNINDENT
107 .UNINDENT
108 .SS Displaying debug output
109 .sp
110 Use \fI\%\-\-verbosity\fP, where it is supported, to specify the amount of
111 notification and debug information that \fBdjango\-admin\fP prints to the console.
112 .SH AVAILABLE COMMANDS
113 .SS \fBcheck\fP
114 .INDENT 0.0
115 .TP
116 .B django\-admin check [app_label [app_label ...]]
117 .UNINDENT
118 .sp
119 Uses the \fI\%system check framework\fP to inspect the entire
120 Django project for common problems.
121 .sp
122 By default, all apps will be checked. You can check a subset of apps by
123 providing a list of app labels as arguments:
124 .INDENT 0.0
125 .INDENT 3.5
126 .sp
127 .EX
128 django\-admin check auth admin myapp
129 .EE
130 .UNINDENT
131 .UNINDENT
132 .INDENT 0.0
133 .TP
134 .B \-\-tag TAGS, \-t TAGS
135 .UNINDENT
136 .sp
137 The system check framework performs many different types of checks that are
138 \fI\%categorized with tags\fP\&. You can use these
139 tags to restrict the checks performed to just those in a particular category.
140 For example, to perform only models and compatibility checks, run:
141 .INDENT 0.0
142 .INDENT 3.5
143 .sp
144 .EX
145 django\-admin check \-\-tag models \-\-tag compatibility
146 .EE
147 .UNINDENT
148 .UNINDENT
149 .INDENT 0.0
150 .TP
151 .B \-\-database DATABASE
152 .UNINDENT
153 .sp
154 Specifies the database to run checks requiring database access:
155 .INDENT 0.0
156 .INDENT 3.5
157 .sp
158 .EX
159 django\-admin check \-\-database default \-\-database other
160 .EE
161 .UNINDENT
162 .UNINDENT
163 .sp
164 By default, these checks will not be run.
165 .INDENT 0.0
166 .TP
167 .B \-\-list\-tags
168 .UNINDENT
169 .sp
170 Lists all available tags.
171 .INDENT 0.0
172 .TP
173 .B \-\-deploy
174 .UNINDENT
175 .sp
176 Activates some additional checks that are only relevant in a deployment setting.
177 .sp
178 You can use this option in your local development environment, but since your
179 local development settings module may not have many of your production settings,
180 you will probably want to point the \fBcheck\fP command at a different settings
181 module, either by setting the \fI\%DJANGO_SETTINGS_MODULE\fP environment
182 variable, or by passing the \fB\-\-settings\fP option:
183 .INDENT 0.0
184 .INDENT 3.5
185 .sp
186 .EX
187 django\-admin check \-\-deploy \-\-settings=production_settings
188 .EE
189 .UNINDENT
190 .UNINDENT
191 .sp
192 Or you could run it directly on a production or staging deployment to verify
193 that the correct settings are in use (omitting \fB\-\-settings\fP). You could even
194 make it part of your integration test suite.
195 .INDENT 0.0
196 .TP
197 .B \-\-fail\-level {CRITICAL,ERROR,WARNING,INFO,DEBUG}
198 .UNINDENT
199 .sp
200 Specifies the message level that will cause the command to exit with a non\-zero
201 status. Default is \fBERROR\fP\&.
202 .SS \fBcompilemessages\fP
203 .INDENT 0.0
204 .TP
205 .B django\-admin compilemessages
206 .UNINDENT
207 .sp
208 Compiles \fB\&.po\fP files created by \fI\%makemessages\fP to \fB\&.mo\fP files for
209 use with the built\-in gettext support. See \fI\%Internationalization and localization\fP\&.
210 .INDENT 0.0
211 .TP
212 .B \-\-locale LOCALE, \-l LOCALE
213 .UNINDENT
214 .sp
215 Specifies the locale(s) to process. If not provided, all locales are processed.
216 .INDENT 0.0
217 .TP
218 .B \-\-exclude EXCLUDE, \-x EXCLUDE
219 .UNINDENT
220 .sp
221 Specifies the locale(s) to exclude from processing. If not provided, no locales
222 are excluded.
223 .INDENT 0.0
224 .TP
225 .B \-\-use\-fuzzy, \-f
226 .UNINDENT
227 .sp
228 Includes \X'tty: link https://www.gnu.org/software/gettext/manual/html_node/Fuzzy-Entries.html'\fI\%fuzzy translations\fP\X'tty: link' into compiled files.
229 .sp
230 Example usage:
231 .INDENT 0.0
232 .INDENT 3.5
233 .sp
234 .EX
235 django\-admin compilemessages \-\-locale=pt_BR
236 django\-admin compilemessages \-\-locale=pt_BR \-\-locale=fr \-f
237 django\-admin compilemessages \-l pt_BR
238 django\-admin compilemessages \-l pt_BR \-l fr \-\-use\-fuzzy
239 django\-admin compilemessages \-\-exclude=pt_BR
240 django\-admin compilemessages \-\-exclude=pt_BR \-\-exclude=fr
241 django\-admin compilemessages \-x pt_BR
242 django\-admin compilemessages \-x pt_BR \-x fr
243 .EE
244 .UNINDENT
245 .UNINDENT
246 .INDENT 0.0
247 .TP
248 .B \-\-ignore PATTERN, \-i PATTERN
249 .UNINDENT
250 .sp
251 Ignores directories matching the given \X'tty: link https://docs.python.org/3/library/glob.html#module-glob'\fI\%glob\fP\X'tty: link'\-style pattern. Use
252 multiple times to ignore more.
253 .sp
254 Example usage:
255 .INDENT 0.0
256 .INDENT 3.5
257 .sp
258 .EX
259 django\-admin compilemessages \-\-ignore=cache \-\-ignore=outdated/*/locale
260 .EE
261 .UNINDENT
262 .UNINDENT
263 .SS \fBcreatecachetable\fP
264 .INDENT 0.0
265 .TP
266 .B django\-admin createcachetable
267 .UNINDENT
268 .sp
269 Creates the cache tables for use with the database cache backend using the
270 information from your settings file. See \fI\%Django\(aqs cache framework\fP for more
271 information.
272 .INDENT 0.0
273 .TP
274 .B \-\-database DATABASE
275 .UNINDENT
276 .sp
277 Specifies the database in which the cache table(s) will be created. Defaults to
278 \fBdefault\fP\&.
279 .INDENT 0.0
280 .TP
281 .B \-\-dry\-run
282 .UNINDENT
283 .sp
284 Prints the SQL that would be run without actually running it, so you can
285 customize it or use the migrations framework.
286 .SS \fBdbshell\fP
287 .INDENT 0.0
288 .TP
289 .B django\-admin dbshell
290 .UNINDENT
291 .sp
292 Runs the command\-line client for the database engine specified in your
293 \fI\%ENGINE\fP setting, with the connection parameters
294 specified in your \fI\%USER\fP, \fI\%PASSWORD\fP, etc., settings.
295 .INDENT 0.0
296 .IP \(bu 2
297 For PostgreSQL, this runs the \fBpsql\fP command\-line client.
298 .IP \(bu 2
299 For MySQL, this runs the \fBmysql\fP command\-line client.
300 .IP \(bu 2
301 For SQLite, this runs the \fBsqlite3\fP command\-line client.
302 .IP \(bu 2
303 For Oracle, this runs the \fBsqlplus\fP command\-line client.
304 .UNINDENT
305 .sp
306 This command assumes the programs are on your \fBPATH\fP so that a call to
307 the program name (\fBpsql\fP, \fBmysql\fP, \fBsqlite3\fP, \fBsqlplus\fP) will find the
308 program in the right place. There\(aqs no way to specify the location of the
309 program manually.
310 .INDENT 0.0
311 .TP
312 .B \-\-database DATABASE
313 .UNINDENT
314 .sp
315 Specifies the database onto which to open a shell. Defaults to \fBdefault\fP\&.
316 .INDENT 0.0
317 .TP
318 .B \-\- ARGUMENTS
319 .UNINDENT
320 .sp
321 Any arguments following a \fB\-\-\fP divider will be passed on to the underlying
322 command\-line client. For example, with PostgreSQL you can use the \fBpsql\fP
323 command\(aqs \fB\-c\fP flag to execute a raw SQL query directly:
324 .INDENT 0.0
325 .INDENT 3.5
326 .sp
327 .EX
328 $ django\-admin dbshell \-\- \-c \(aqselect current_user\(aq
329 current_user
330 \-\-\-\-\-\-\-\-\-\-\-\-\-\-
331 postgres
332 (1 row)
333 .EE
334 .UNINDENT
335 .UNINDENT
336 .sp
337 On MySQL/MariaDB, you can do this with the \fBmysql\fP command\(aqs \fB\-e\fP flag:
338 .INDENT 0.0
339 .INDENT 3.5
340 .sp
341 .EX
342 $ django\-admin dbshell \-\- \-e \(dqselect user()\(dq
343 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
344 | user() |
345 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
346 | djangonaut@localhost |
347 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
348 .EE
349 .UNINDENT
350 .UNINDENT
351 .sp
352 \fBNOTE:\fP
353 .INDENT 0.0
354 .INDENT 3.5
355 Be aware that not all options set in the \fI\%OPTIONS\fP part of your
356 database configuration in \fI\%DATABASES\fP are passed to the
357 command\-line client, e.g. \fB\(aqisolation_level\(aq\fP\&.
358 .UNINDENT
359 .UNINDENT
360 .SS \fBdiffsettings\fP
361 .INDENT 0.0
362 .TP
363 .B django\-admin diffsettings
364 .UNINDENT
365 .sp
366 Displays differences between the current settings file and Django\(aqs default
367 settings (or another settings file specified by \fI\%\-\-default\fP).
368 .sp
369 Settings that don\(aqt appear in the defaults are followed by \fB\(dq###\(dq\fP\&. For
370 example, the default settings don\(aqt define \fI\%ROOT_URLCONF\fP, so
371 \fI\%ROOT_URLCONF\fP is followed by \fB\(dq###\(dq\fP in the output of
372 \fBdiffsettings\fP\&.
373 .INDENT 0.0
374 .TP
375 .B \-\-all
376 .UNINDENT
377 .sp
378 Displays all settings, even if they have Django\(aqs default value. Such settings
379 are prefixed by \fB\(dq###\(dq\fP\&.
380 .INDENT 0.0
381 .TP
382 .B \-\-default MODULE
383 .UNINDENT
384 .sp
385 The settings module to compare the current settings against. Leave empty to
386 compare against Django\(aqs default settings.
387 .INDENT 0.0
388 .TP
389 .B \-\-output {hash,unified}
390 .UNINDENT
391 .sp
392 Specifies the output format. Available values are \fBhash\fP and \fBunified\fP\&.
393 \fBhash\fP is the default mode that displays the output that\(aqs described above.
394 \fBunified\fP displays the output similar to \fBdiff \-u\fP\&. Default settings are
395 prefixed with a minus sign, followed by the changed setting prefixed with a
396 plus sign.
397 .SS \fBdumpdata\fP
398 .INDENT 0.0
399 .TP
400 .B django\-admin dumpdata [app_label[.ModelName] [app_label[.ModelName] ...]]
401 .UNINDENT
402 .sp
403 Outputs to standard output all data in the database associated with the named
404 application(s).
405 .sp
406 If no application name is provided, all installed applications will be dumped.
407 .sp
408 The output of \fBdumpdata\fP can be used as input for \fI\%loaddata\fP\&.
409 .sp
410 When result of \fBdumpdata\fP is saved as a file, it can serve as a
411 \fI\%fixture\fP for
412 \fI\%tests\fP or as an
413 \fI\%initial data\fP\&.
414 .sp
415 Note that \fBdumpdata\fP uses the default manager on the model for selecting the
416 records to dump. If you\(aqre using a \fI\%custom manager\fP as
417 the default manager and it filters some of the available records, not all of the
418 objects will be dumped.
419 .INDENT 0.0
420 .TP
421 .B \-\-all, \-a
422 .UNINDENT
423 .sp
424 Uses Django\(aqs base manager, dumping records which might otherwise be filtered
425 or modified by a custom manager.
426 .INDENT 0.0
427 .TP
428 .B \-\-format FORMAT
429 .UNINDENT
430 .sp
431 Specifies the serialization format of the output. Defaults to JSON. Supported
432 formats are listed in \fI\%Serialization formats\fP\&.
433 .INDENT 0.0
434 .TP
435 .B \-\-indent INDENT
436 .UNINDENT
437 .sp
438 Specifies the number of indentation spaces to use in the output. Defaults to
439 \fBNone\fP which displays all data on single line.
440 .INDENT 0.0
441 .TP
442 .B \-\-exclude EXCLUDE, \-e EXCLUDE
443 .UNINDENT
444 .sp
445 Prevents specific applications or models (specified in the form of
446 \fBapp_label.ModelName\fP) from being dumped. If you specify a model name, then
447 only that model will be excluded, rather than the entire application. You can
448 also mix application names and model names.
449 .sp
450 If you want to exclude multiple applications, pass \fB\-\-exclude\fP more than
451 once:
452 .INDENT 0.0
453 .INDENT 3.5
454 .sp
455 .EX
456 django\-admin dumpdata \-\-exclude=auth \-\-exclude=contenttypes
457 .EE
458 .UNINDENT
459 .UNINDENT
460 .INDENT 0.0
461 .TP
462 .B \-\-database DATABASE
463 .UNINDENT
464 .sp
465 Specifies the database from which data will be dumped. Defaults to \fBdefault\fP\&.
466 .INDENT 0.0
467 .TP
468 .B \-\-natural\-foreign
469 .UNINDENT
470 .sp
471 Uses the \fBnatural_key()\fP model method to serialize any foreign key and
472 many\-to\-many relationship to objects of the type that defines the method. If
473 you\(aqre dumping \fBcontrib.auth\fP \fBPermission\fP objects or
474 \fBcontrib.contenttypes\fP \fBContentType\fP objects, you should probably use this
475 flag. See the \fI\%natural keys\fP
476 documentation for more details on this and the next option.
477 .INDENT 0.0
478 .TP
479 .B \-\-natural\-primary
480 .UNINDENT
481 .sp
482 Omits the primary key in the serialized data of this object since it can be
483 calculated during deserialization.
484 .INDENT 0.0
485 .TP
486 .B \-\-pks PRIMARY_KEYS
487 .UNINDENT
488 .sp
489 Outputs only the objects specified by a comma separated list of primary keys.
490 This is only available when dumping one model. By default, all the records of
491 the model are output.
492 .INDENT 0.0
493 .TP
494 .B \-\-output OUTPUT, \-o OUTPUT
495 .UNINDENT
496 .sp
497 Specifies a file to write the serialized data to. By default, the data goes to
498 standard output.
499 .sp
500 When this option is set and \fB\-\-verbosity\fP is greater than 0 (the default), a
501 progress bar is shown in the terminal.
502 .SS Fixtures compression
503 .sp
504 The output file can be compressed with one of the \fBbz2\fP, \fBgz\fP, \fBlzma\fP, or
505 \fBxz\fP formats by ending the filename with the corresponding extension.
506 For example, to output the data as a compressed JSON file:
507 .INDENT 0.0
508 .INDENT 3.5
509 .sp
510 .EX
511 django\-admin dumpdata \-o mydata.json.gz
512 .EE
513 .UNINDENT
514 .UNINDENT
515 .SS \fBflush\fP
516 .INDENT 0.0
517 .TP
518 .B django\-admin flush
519 .UNINDENT
520 .sp
521 Removes all data from the database and re\-executes any post\-synchronization
522 handlers. The table of which migrations have been applied is not cleared.
523 .sp
524 If you would rather start from an empty database and rerun all migrations, you
525 should drop and recreate the database and then run \fI\%migrate\fP instead.
526 .INDENT 0.0
527 .TP
528 .B \-\-noinput, \-\-no\-input
529 .UNINDENT
530 .sp
531 Suppresses all user prompts.
532 .INDENT 0.0
533 .TP
534 .B \-\-database DATABASE
535 .UNINDENT
536 .sp
537 Specifies the database to flush. Defaults to \fBdefault\fP\&.
538 .SS \fBinspectdb\fP
539 .INDENT 0.0
540 .TP
541 .B django\-admin inspectdb [table [table ...]]
542 .UNINDENT
543 .sp
544 Introspects the database tables in the database pointed\-to by the
545 \fI\%NAME\fP setting and outputs a Django model module (a \fBmodels.py\fP
546 file) to standard output.
547 .sp
548 You may choose what tables or views to inspect by passing their names as
549 arguments. If no arguments are provided, models are created for views only if
550 the \fI\%\-\-include\-views\fP option is used. Models for partition tables are
551 created on PostgreSQL if the \fI\%\-\-include\-partitions\fP option is used.
552 .sp
553 Use this if you have a legacy database with which you\(aqd like to use Django.
554 The script will inspect the database and create a model for each table within
555 it.
556 .sp
557 As you might expect, the created models will have an attribute for every field
558 in the table. Note that \fBinspectdb\fP has a few special cases in its field\-name
559 output:
560 .INDENT 0.0
561 .IP \(bu 2
562 If \fBinspectdb\fP cannot map a column\(aqs type to a model field type, it\(aqll
563 use \fBTextField\fP and will insert the Python comment
564 \fB\(aqThis field type is a guess.\(aq\fP next to the field in the generated
565 model. The recognized fields may depend on apps listed in
566 \fI\%INSTALLED_APPS\fP\&. For example, \fI\%django.contrib.postgres\fP adds
567 recognition for several PostgreSQL\-specific field types.
568 .IP \(bu 2
569 If the database column name is a Python reserved word (such as
570 \fB\(aqpass\(aq\fP, \fB\(aqclass\(aq\fP or \fB\(aqfor\(aq\fP), \fBinspectdb\fP will append
571 \fB\(aq_field\(aq\fP to the attribute name. For example, if a table has a column
572 \fB\(aqfor\(aq\fP, the generated model will have a field \fB\(aqfor_field\(aq\fP, with
573 the \fBdb_column\fP attribute set to \fB\(aqfor\(aq\fP\&. \fBinspectdb\fP will insert
574 the Python comment
575 \fB\(aqField renamed because it was a Python reserved word.\(aq\fP next to the
576 field.
577 .UNINDENT
578 .sp
579 This feature is meant as a shortcut, not as definitive model generation. After
580 you run it, you\(aqll want to look over the generated models yourself to make
581 customizations. In particular, you\(aqll need to rearrange models\(aq order, so that
582 models that refer to other models are ordered properly.
583 .sp
584 Django doesn\(aqt create database defaults when a
585 \fI\%default\fP is specified on a model field.
586 Similarly, database defaults aren\(aqt translated to model field defaults or
587 detected in any fashion by \fBinspectdb\fP\&.
588 .sp
589 By default, \fBinspectdb\fP creates unmanaged models. That is, \fBmanaged = False\fP
590 in the model\(aqs \fBMeta\fP class tells Django not to manage each table\(aqs creation,
591 modification, and deletion. If you do want to allow Django to manage the
592 table\(aqs lifecycle, you\(aqll need to change the
593 \fI\%managed\fP option to \fBTrue\fP (or remove
594 it because \fBTrue\fP is its default value).
595 .SS Database\-specific notes
596 .SS Oracle
597 .INDENT 0.0
598 .IP \(bu 2
599 Models are created for materialized views if \fI\%\-\-include\-views\fP is
600 used.
601 .UNINDENT
602 .SS PostgreSQL
603 .INDENT 0.0
604 .IP \(bu 2
605 Models are created for foreign tables.
606 .IP \(bu 2
607 Models are created for materialized views if
608 \fI\%\-\-include\-views\fP is used.
609 .IP \(bu 2
610 Models are created for partition tables if
611 \fI\%\-\-include\-partitions\fP is used.
612 .UNINDENT
613 .INDENT 0.0
614 .TP
615 .B \-\-database DATABASE
616 .UNINDENT
617 .sp
618 Specifies the database to introspect. Defaults to \fBdefault\fP\&.
619 .INDENT 0.0
620 .TP
621 .B \-\-include\-partitions
622 .UNINDENT
623 .sp
624 If this option is provided, models are also created for partitions.
625 .sp
626 Only support for PostgreSQL is implemented.
627 .INDENT 0.0
628 .TP
629 .B \-\-include\-views
630 .UNINDENT
631 .sp
632 If this option is provided, models are also created for database views.
633 .SS \fBloaddata\fP
634 .INDENT 0.0
635 .TP
636 .B django\-admin loaddata fixture [fixture ...]
637 .UNINDENT
638 .sp
639 Searches for and loads the contents of the named
640 \fI\%fixture\fP into the database.
641 .INDENT 0.0
642 .TP
643 .B \-\-database DATABASE
644 .UNINDENT
645 .sp
646 Specifies the database into which the data will be loaded. Defaults to
647 \fBdefault\fP\&.
648 .INDENT 0.0
649 .TP
650 .B \-\-ignorenonexistent, \-i
651 .UNINDENT
652 .sp
653 Ignores fields and models that may have been removed since the fixture was
654 originally generated.
655 .INDENT 0.0
656 .TP
657 .B \-\-app APP_LABEL
658 .UNINDENT
659 .sp
660 Specifies a single app to look for fixtures in rather than looking in all apps.
661 .INDENT 0.0
662 .TP
663 .B \-\-format FORMAT
664 .UNINDENT
665 .sp
666 Specifies the \fI\%serialization format\fP (e.g.,
667 \fBjson\fP or \fBxml\fP) for fixtures \fI\%read from stdin\fP\&.
668 .INDENT 0.0
669 .TP
670 .B \-\-exclude EXCLUDE, \-e EXCLUDE
671 .UNINDENT
672 .sp
673 Excludes loading the fixtures from the given applications and/or models (in the
674 form of \fBapp_label\fP or \fBapp_label.ModelName\fP). Use the option multiple
675 times to exclude more than one app or model.
676 .SS Loading fixtures from \fBstdin\fP
677 .sp
678 You can use a dash as the fixture name to load input from \fBsys.stdin\fP\&. For
679 example:
680 .INDENT 0.0
681 .INDENT 3.5
682 .sp
683 .EX
684 django\-admin loaddata \-\-format=json \-
685 .EE
686 .UNINDENT
687 .UNINDENT
688 .sp
689 When reading from \fBstdin\fP, the \fI\%\-\-format\fP option
690 is required to specify the \fI\%serialization format\fP
691 of the input (e.g., \fBjson\fP or \fBxml\fP).
692 .sp
693 Loading from \fBstdin\fP is useful with standard input and output redirections.
694 For example:
695 .INDENT 0.0
696 .INDENT 3.5
697 .sp
698 .EX
699 django\-admin dumpdata \-\-format=json \-\-database=test app_label.ModelName | django\-admin loaddata \-\-format=json \-\-database=prod \-
700 .EE
701 .UNINDENT
702 .UNINDENT
703 .sp
704 The \fI\%dumpdata\fP command can be used to generate input for \fBloaddata\fP\&.
705 .sp
706 \fBSEE ALSO:\fP
707 .INDENT 0.0
708 .INDENT 3.5
709 For more detail about fixtures see the \fI\%Fixtures\fP topic.
710 .UNINDENT
711 .UNINDENT
712 .SS \fBmakemessages\fP
713 .INDENT 0.0
714 .TP
715 .B django\-admin makemessages
716 .UNINDENT
717 .sp
718 Runs over the entire source tree of the current directory and pulls out all
719 strings marked for translation. It creates (or updates) a message file in the
720 conf/locale (in the Django tree) or locale (for project and application)
721 directory. After making changes to the messages files you need to compile them
722 with \fI\%compilemessages\fP for use with the builtin gettext support. See
723 the \fI\%i18n documentation\fP for details.
724 .sp
725 This command doesn\(aqt require configured settings. However, when settings aren\(aqt
726 configured, the command can\(aqt ignore the \fI\%MEDIA_ROOT\fP and
727 \fI\%STATIC_ROOT\fP directories or include \fI\%LOCALE_PATHS\fP\&.
728 .INDENT 0.0
729 .TP
730 .B \-\-all, \-a
731 .UNINDENT
732 .sp
733 Updates the message files for all available languages.
734 .INDENT 0.0
735 .TP
736 .B \-\-extension EXTENSIONS, \-e EXTENSIONS
737 .UNINDENT
738 .sp
739 Specifies a list of file extensions to examine (default: \fBhtml\fP, \fBtxt\fP,
740 \fBpy\fP or \fBjs\fP if \fI\%\-\-domain\fP is \fBdjangojs\fP).
741 .sp
742 Example usage:
743 .INDENT 0.0
744 .INDENT 3.5
745 .sp
746 .EX
747 django\-admin makemessages \-\-locale=de \-\-extension xhtml
748 .EE
749 .UNINDENT
750 .UNINDENT
751 .sp
752 Separate multiple extensions with commas or use \fB\-e\fP or \fB\-\-extension\fP
753 multiple times:
754 .INDENT 0.0
755 .INDENT 3.5
756 .sp
757 .EX
758 django\-admin makemessages \-\-locale=de \-\-extension=html,txt \-\-extension xml
759 .EE
760 .UNINDENT
761 .UNINDENT
762 .INDENT 0.0
763 .TP
764 .B \-\-locale LOCALE, \-l LOCALE
765 .UNINDENT
766 .sp
767 Specifies the locale(s) to process.
768 .INDENT 0.0
769 .TP
770 .B \-\-exclude EXCLUDE, \-x EXCLUDE
771 .UNINDENT
772 .sp
773 Specifies the locale(s) to exclude from processing. If not provided, no locales
774 are excluded.
775 .sp
776 Example usage:
777 .INDENT 0.0
778 .INDENT 3.5
779 .sp
780 .EX
781 django\-admin makemessages \-\-locale=pt_BR
782 django\-admin makemessages \-\-locale=pt_BR \-\-locale=fr
783 django\-admin makemessages \-l pt_BR
784 django\-admin makemessages \-l pt_BR \-l fr
785 django\-admin makemessages \-\-exclude=pt_BR
786 django\-admin makemessages \-\-exclude=pt_BR \-\-exclude=fr
787 django\-admin makemessages \-x pt_BR
788 django\-admin makemessages \-x pt_BR \-x fr
789 .EE
790 .UNINDENT
791 .UNINDENT
792 .INDENT 0.0
793 .TP
794 .B \-\-domain DOMAIN, \-d DOMAIN
795 .UNINDENT
796 .sp
797 Specifies the domain of the messages files. Supported options are:
798 .INDENT 0.0
799 .IP \(bu 2
800 \fBdjango\fP for all \fB*.py\fP, \fB*.html\fP and \fB*.txt\fP files (default)
801 .IP \(bu 2
802 \fBdjangojs\fP for \fB*.js\fP files
803 .UNINDENT
804 .INDENT 0.0
805 .TP
806 .B \-\-symlinks, \-s
807 .UNINDENT
808 .sp
809 Follows symlinks to directories when looking for new translation strings.
810 .sp
811 Example usage:
812 .INDENT 0.0
813 .INDENT 3.5
814 .sp
815 .EX
816 django\-admin makemessages \-\-locale=de \-\-symlinks
817 .EE
818 .UNINDENT
819 .UNINDENT
820 .INDENT 0.0
821 .TP
822 .B \-\-ignore PATTERN, \-i PATTERN
823 .UNINDENT
824 .sp
825 Ignores files or directories matching the given \X'tty: link https://docs.python.org/3/library/glob.html#module-glob'\fI\%glob\fP\X'tty: link'\-style pattern. Use
826 multiple times to ignore more.
827 .sp
828 These patterns are used by default: \fB\(aqCVS\(aq\fP, \fB\(aq.*\(aq\fP, \fB\(aq*~\(aq\fP, \fB\(aq*.pyc\(aq\fP\&.
829 .sp
830 Example usage:
831 .INDENT 0.0
832 .INDENT 3.5
833 .sp
834 .EX
835 django\-admin makemessages \-\-locale=en_US \-\-ignore=apps/* \-\-ignore=secret/*.html
836 .EE
837 .UNINDENT
838 .UNINDENT
839 .INDENT 0.0
840 .TP
841 .B \-\-no\-default\-ignore
842 .UNINDENT
843 .sp
844 Disables the default values of \fB\-\-ignore\fP\&.
845 .INDENT 0.0
846 .TP
847 .B \-\-no\-wrap
848 .UNINDENT
849 .sp
850 Disables breaking long message lines into several lines in language files.
851 .INDENT 0.0
852 .TP
853 .B \-\-no\-location
854 .UNINDENT
855 .sp
856 Suppresses writing \(aq\fB#: filename:line\fP’ comment lines in language files.
857 Using this option makes it harder for technically skilled translators to
858 understand each message\(aqs context.
859 .INDENT 0.0
860 .TP
861 .B \-\-add\-location [{full,file,never}]
862 .UNINDENT
863 .sp
864 Controls \fB#: filename:line\fP comment lines in language files. If the option
865 is:
866 .INDENT 0.0
867 .IP \(bu 2
868 \fBfull\fP (the default if not given): the lines include both file name and
869 line number.
870 .IP \(bu 2
871 \fBfile\fP: the line number is omitted.
872 .IP \(bu 2
873 \fBnever\fP: the lines are suppressed (same as \fI\%\-\-no\-location\fP).
874 .UNINDENT
875 .sp
876 Requires \fBgettext\fP 0.19 or newer.
877 .INDENT 0.0
878 .TP
879 .B \-\-no\-obsolete
880 .UNINDENT
881 .sp
882 Removes obsolete message strings from the \fB\&.po\fP files.
883 .INDENT 0.0
884 .TP
885 .B \-\-keep\-pot
886 .UNINDENT
887 .sp
888 Prevents deleting the temporary \fB\&.pot\fP files generated before creating the
889 \fB\&.po\fP file. This is useful for debugging errors which may prevent the final
890 language files from being created.
891 .sp
892 \fBSEE ALSO:\fP
893 .INDENT 0.0
894 .INDENT 3.5
895 See \fI\%Customizing the makemessages command\fP for instructions on how to customize
896 the keywords that \fI\%makemessages\fP passes to \fBxgettext\fP\&.
897 .UNINDENT
898 .UNINDENT
899 .SS \fBmakemigrations\fP
900 .INDENT 0.0
901 .TP
902 .B django\-admin makemigrations [app_label [app_label ...]]
903 .UNINDENT
904 .sp
905 Creates new migrations based on the changes detected to your models.
906 Migrations, their relationship with apps and more are covered in depth in
907 \fI\%the migrations documentation\fP\&.
908 .sp
909 Providing one or more app names as arguments will limit the migrations created
910 to the app(s) specified and any dependencies needed (the table at the other end
911 of a \fBForeignKey\fP, for example).
912 .sp
913 To add migrations to an app that doesn\(aqt have a \fBmigrations\fP directory, run
914 \fBmakemigrations\fP with the app\(aqs \fBapp_label\fP\&.
915 .INDENT 0.0
916 .TP
917 .B \-\-noinput, \-\-no\-input
918 .UNINDENT
919 .sp
920 Suppresses all user prompts. If a suppressed prompt cannot be resolved
921 automatically, the command will exit with error code 3.
922 .INDENT 0.0
923 .TP
924 .B \-\-empty
925 .UNINDENT
926 .sp
927 Outputs an empty migration for the specified apps, for manual editing. This is
928 for advanced users and should not be used unless you are familiar with the
929 migration format, migration operations, and the dependencies between your
930 migrations.
931 .INDENT 0.0
932 .TP
933 .B \-\-dry\-run
934 .UNINDENT
935 .sp
936 Shows what migrations would be made without actually writing any migrations
937 files to disk. Using this option along with \fB\-\-verbosity 3\fP will also show
938 the complete migrations files that would be written.
939 .INDENT 0.0
940 .TP
941 .B \-\-merge
942 .UNINDENT
943 .sp
944 Enables fixing of migration conflicts.
945 .INDENT 0.0
946 .TP
947 .B \-\-name NAME, \-n NAME
948 .UNINDENT
949 .sp
950 Allows naming the generated migration(s) instead of using a generated name. The
951 name must be a valid Python \X'tty: link https://docs.python.org/3/reference/lexical_analysis.html#identifiers'\fI\%identifier\fP\X'tty: link'\&.
952 .INDENT 0.0
953 .TP
954 .B \-\-no\-header
955 .UNINDENT
956 .sp
957 Generate migration files without Django version and timestamp header.
958 .INDENT 0.0
959 .TP
960 .B \-\-check
961 .UNINDENT
962 .sp
963 Makes \fBmakemigrations\fP exit with a non\-zero status when model changes without
964 migrations are detected. Implies \fB\-\-dry\-run\fP\&.
965 .INDENT 0.0
966 .TP
967 .B \-\-scriptable
968 .UNINDENT
969 .sp
970 Diverts log output and input prompts to \fBstderr\fP, writing only paths of
971 generated migration files to \fBstdout\fP\&.
972 .INDENT 0.0
973 .TP
974 .B \-\-update
975 .UNINDENT
976 .sp
977 Merges model changes into the latest migration and optimize the resulting
978 operations.
979 .sp
980 The updated migration will have a generated name. In order to preserve the
981 previous name, set it using \fB\-\-name\fP\&.
982 .SS \fBmigrate\fP
983 .INDENT 0.0
984 .TP
985 .B django\-admin migrate [app_label] [migration_name]
986 .UNINDENT
987 .sp
988 Synchronizes the database state with the current set of models and migrations.
989 Migrations, their relationship with apps and more are covered in depth in
990 \fI\%the migrations documentation\fP\&.
991 .sp
992 The behavior of this command changes depending on the arguments provided:
993 .INDENT 0.0
994 .IP \(bu 2
995 No arguments: All apps have all of their migrations run.
996 .IP \(bu 2
997 \fB<app_label>\fP: The specified app has its migrations run, up to the most
998 recent migration. This may involve running other apps\(aq migrations too, due
999 to dependencies.
1000 .IP \(bu 2
1001 \fB<app_label> <migrationname>\fP: Brings the database schema to a state where
1002 the named migration is applied, but no later migrations in the same app are
1003 applied. This may involve unapplying migrations if you have previously
1004 migrated past the named migration. You can use a prefix of the migration
1005 name, e.g. \fB0001\fP, as long as it\(aqs unique for the given app name. Use the
1006 name \fBzero\fP to migrate all the way back i.e. to revert all applied
1007 migrations for an app.
1008 .UNINDENT
1009 .sp
1010 \fBWARNING:\fP
1011 .INDENT 0.0
1012 .INDENT 3.5
1013 When unapplying migrations, all dependent migrations will also be
1014 unapplied, regardless of \fB<app_label>\fP\&. You can use \fB\-\-plan\fP to check
1015 which migrations will be unapplied.
1016 .UNINDENT
1017 .UNINDENT
1018 .INDENT 0.0
1019 .TP
1020 .B \-\-database DATABASE
1021 .UNINDENT
1022 .sp
1023 Specifies the database to migrate. Defaults to \fBdefault\fP\&.
1024 .INDENT 0.0
1025 .TP
1026 .B \-\-fake
1027 .UNINDENT
1028 .sp
1029 Marks the migrations up to the target one (following the rules above) as
1030 applied, but without actually running the SQL to change your database schema.
1031 .sp
1032 This is intended for advanced users to manipulate the
1033 current migration state directly if they\(aqre manually applying changes;
1034 be warned that using \fB\-\-fake\fP runs the risk of putting the migration state
1035 table into a state where manual recovery will be needed to make migrations
1036 run correctly.
1037 .INDENT 0.0
1038 .TP
1039 .B \-\-fake\-initial
1040 .UNINDENT
1041 .sp
1042 Allows Django to skip an app\(aqs initial migration if all database tables with
1043 the names of all models created by all
1044 \fI\%CreateModel\fP operations in that
1045 migration already exist. This option is intended for use when first running
1046 migrations against a database that preexisted the use of migrations. This
1047 option does not, however, check for matching database schema beyond matching
1048 table names and so is only safe to use if you are confident that your existing
1049 schema matches what is recorded in your initial migration.
1050 .INDENT 0.0
1051 .TP
1052 .B \-\-plan
1053 .UNINDENT
1054 .sp
1055 Shows the migration operations that will be performed for the given \fBmigrate\fP
1056 command.
1057 .INDENT 0.0
1058 .TP
1059 .B \-\-run\-syncdb
1060 .UNINDENT
1061 .sp
1062 Allows creating tables for apps without migrations. While this isn\(aqt
1063 recommended, the migrations framework is sometimes too slow on large projects
1064 with hundreds of models.
1065 .INDENT 0.0
1066 .TP
1067 .B \-\-noinput, \-\-no\-input
1068 .UNINDENT
1069 .sp
1070 Suppresses all user prompts. An example prompt is asking about removing stale
1071 content types.
1072 .INDENT 0.0
1073 .TP
1074 .B \-\-check
1075 .UNINDENT
1076 .sp
1077 Makes \fBmigrate\fP exit with a non\-zero status when unapplied migrations are
1078 detected.
1079 .INDENT 0.0
1080 .TP
1081 .B \-\-prune
1082 .UNINDENT
1083 .sp
1084 Deletes nonexistent migrations from the \fBdjango_migrations\fP table. This is
1085 useful when migration files replaced by a squashed migration have been removed.
1086 See \fI\%Squashing migrations\fP for more details.
1087 .SS \fBoptimizemigration\fP
1088 .INDENT 0.0
1089 .TP
1090 .B django\-admin optimizemigration app_label migration_name
1091 .UNINDENT
1092 .sp
1093 Optimizes the operations for the named migration and overrides the existing
1094 file. If the migration contains functions that must be manually copied, the
1095 command creates a new migration file suffixed with \fB_optimized\fP that is meant
1096 to replace the named migration.
1097 .INDENT 0.0
1098 .TP
1099 .B \-\-check
1100 .UNINDENT
1101 .sp
1102 Makes \fBoptimizemigration\fP exit with a non\-zero status when a migration can be
1103 optimized.
1104 .SS \fBrunserver\fP
1105 .INDENT 0.0
1106 .TP
1107 .B django\-admin runserver [addrport]
1108 .UNINDENT
1109 .sp
1110 Starts a lightweight development web server on the local machine. By default,
1111 the server runs on port 8000 on the IP address \fB127.0.0.1\fP\&. You can pass in an
1112 IP address and port number explicitly.
1113 .sp
1114 If you run this script as a user with normal privileges (recommended), you
1115 might not have access to start a port on a low port number. Low port numbers
1116 are reserved for the superuser (root).
1117 .sp
1118 This server uses the WSGI application object specified by the
1119 \fI\%WSGI_APPLICATION\fP setting.
1120 .sp
1121 \fBWARNING:\fP
1122 .INDENT 0.0
1123 .INDENT 3.5
1124 DO NOT USE THIS SERVER IN A PRODUCTION SETTING.
1125 .sp
1126 This lightweight development server has not gone through security audits or
1127 performance tests, hence is unsuitable for production. Making this server
1128 able to handle a production environment is outside the scope of Django.
1129 .UNINDENT
1130 .UNINDENT
1131 .sp
1132 The development server automatically reloads Python code for each request, as
1133 needed. You don\(aqt need to restart the server for code changes to take effect.
1134 However, some actions like adding files don\(aqt trigger a restart, so you\(aqll
1135 have to restart the server in these cases.
1136 .sp
1137 If you\(aqre using Linux or MacOS and install both \X'tty: link https://pypi.org/project/pywatchman/'\fI\%pywatchman\fP\X'tty: link' and the
1138 \X'tty: link https://facebook.github.io/watchman/'\fI\%Watchman\fP\X'tty: link' service, kernel signals will be used to autoreload the server
1139 (rather than polling file modification timestamps each second). This offers
1140 better performance on large projects, reduced response time after code changes,
1141 more robust change detection, and a reduction in power usage. Django supports
1142 \fBpywatchman\fP 1.2.0 and higher.
1143 .INDENT 0.0
1144 .INDENT 3.5
1145 .IP "Large directories with many files may cause performance issues"
1146 .sp
1147 When using Watchman with a project that includes large non\-Python
1148 directories like \fBnode_modules\fP, it\(aqs advisable to ignore this directory
1149 for optimal performance. See the \X'tty: link https://facebook.github.io/watchman/docs/config#ignore_dirs'\fI\%watchman documentation\fP\X'tty: link' for information
1150 on how to do this.
1151 .UNINDENT
1152 .UNINDENT
1153 .INDENT 0.0
1154 .INDENT 3.5
1155 .IP "Watchman timeout"
1156 .INDENT 0.0
1157 .TP
1158 .B DJANGO_WATCHMAN_TIMEOUT
1159 .UNINDENT
1160 .sp
1161 The default timeout of \fBWatchman\fP client is 5 seconds. You can change it
1162 by setting the \fI\%DJANGO_WATCHMAN_TIMEOUT\fP environment variable.
1163 .UNINDENT
1164 .UNINDENT
1165 .sp
1166 When you start the server, and each time you change Python code while the
1167 server is running, the system check framework will check your entire Django
1168 project for some common errors (see the \fI\%check\fP command). If any
1169 errors are found, they will be printed to standard output. You can use the
1170 \fB\-\-skip\-checks\fP option to skip running system checks.
1171 .sp
1172 You can run as many concurrent servers as you want, as long as they\(aqre on
1173 separate ports by executing \fBdjango\-admin runserver\fP more than once.
1174 .sp
1175 Note that the default IP address, \fB127.0.0.1\fP, is not accessible from other
1176 machines on your network. To make your development server viewable to other
1177 machines on the network, use its own IP address (e.g. \fB192.168.2.1\fP), \fB0\fP
1178 (shortcut for \fB0.0.0.0\fP), \fB0.0.0.0\fP, or \fB::\fP (with IPv6 enabled).
1179 .sp
1180 You can provide an IPv6 address surrounded by brackets
1181 (e.g. \fB[200a::1]:8000\fP). This will automatically enable IPv6 support.
1182 .sp
1183 A hostname containing ASCII\-only characters can also be used.
1184 .sp
1185 If the \fI\%staticfiles\fP contrib app is enabled
1186 (default in new projects) the \fI\%runserver\fP command will be overridden
1187 with its own \fI\%runserver\fP command.
1188 .sp
1189 Logging of each request and response of the server is sent to the
1190 \fI\%django.server\fP logger.
1191 .INDENT 0.0
1192 .TP
1193 .B \-\-noreload
1194 .UNINDENT
1195 .sp
1196 Disables the auto\-reloader. This means any Python code changes you make while
1197 the server is running will \fInot\fP take effect if the particular Python modules
1198 have already been loaded into memory.
1199 .INDENT 0.0
1200 .TP
1201 .B \-\-nothreading
1202 .UNINDENT
1203 .sp
1204 Disables use of threading in the development server. The server is
1205 multithreaded by default.
1206 .INDENT 0.0
1207 .TP
1208 .B \-\-ipv6, \-6
1209 .UNINDENT
1210 .sp
1211 Uses IPv6 for the development server. This changes the default IP address from
1212 \fB127.0.0.1\fP to \fB::1\fP\&.
1213 .INDENT 0.0
1214 .TP
1215 .B DJANGO_RUNSERVER_HIDE_WARNING
1216 .UNINDENT
1217 .sp
1218
1219 .sp
1220 By default, a warning is printed to the console that \fBrunserver\fP is not
1221 suitable for production:
1222 .INDENT 0.0
1223 .INDENT 3.5
1224 .sp
1225 .EX
1226 WARNING: This is a development server. Do not use it in a production setting. Use a production WSGI or ASGI server instead.
1227 For more information on production servers see: https://docs.djangoproject.com/en/|version|/howto/deployment/
1228 .EE
1229 .UNINDENT
1230 .UNINDENT
1231 .sp
1232 Set this environment variable to \fB\(dqtrue\(dq\fP to hide this warning.
1233 .SS Examples of using different ports and addresses
1234 .sp
1235 Port 8000 on IP address \fB127.0.0.1\fP:
1236 .INDENT 0.0
1237 .INDENT 3.5
1238 .sp
1239 .EX
1240 django\-admin runserver
1241 .EE
1242 .UNINDENT
1243 .UNINDENT
1244 .sp
1245 Port 8000 on IP address \fB1.2.3.4\fP:
1246 .INDENT 0.0
1247 .INDENT 3.5
1248 .sp
1249 .EX
1250 django\-admin runserver 1.2.3.4:8000
1251 .EE
1252 .UNINDENT
1253 .UNINDENT
1254 .sp
1255 Port 7000 on IP address \fB127.0.0.1\fP:
1256 .INDENT 0.0
1257 .INDENT 3.5
1258 .sp
1259 .EX
1260 django\-admin runserver 7000
1261 .EE
1262 .UNINDENT
1263 .UNINDENT
1264 .sp
1265 Port 7000 on IP address \fB1.2.3.4\fP:
1266 .INDENT 0.0
1267 .INDENT 3.5
1268 .sp
1269 .EX
1270 django\-admin runserver 1.2.3.4:7000
1271 .EE
1272 .UNINDENT
1273 .UNINDENT
1274 .sp
1275 Port 8000 on IPv6 address \fB::1\fP:
1276 .INDENT 0.0
1277 .INDENT 3.5
1278 .sp
1279 .EX
1280 django\-admin runserver \-6
1281 .EE
1282 .UNINDENT
1283 .UNINDENT
1284 .sp
1285 Port 7000 on IPv6 address \fB::1\fP:
1286 .INDENT 0.0
1287 .INDENT 3.5
1288 .sp
1289 .EX
1290 django\-admin runserver \-6 7000
1291 .EE
1292 .UNINDENT
1293 .UNINDENT
1294 .sp
1295 Port 7000 on IPv6 address \fB2001:0db8:1234:5678::9\fP:
1296 .INDENT 0.0
1297 .INDENT 3.5
1298 .sp
1299 .EX
1300 django\-admin runserver [2001:0db8:1234:5678::9]:7000
1301 .EE
1302 .UNINDENT
1303 .UNINDENT
1304 .sp
1305 Port 8000 on IPv4 address of host \fBlocalhost\fP:
1306 .INDENT 0.0
1307 .INDENT 3.5
1308 .sp
1309 .EX
1310 django\-admin runserver localhost:8000
1311 .EE
1312 .UNINDENT
1313 .UNINDENT
1314 .sp
1315 Port 8000 on IPv6 address of host \fBlocalhost\fP:
1316 .INDENT 0.0
1317 .INDENT 3.5
1318 .sp
1319 .EX
1320 django\-admin runserver \-6 localhost:8000
1321 .EE
1322 .UNINDENT
1323 .UNINDENT
1324 .SS Serving static files with the development server
1325 .sp
1326 By default, the development server doesn\(aqt serve any static files for your site
1327 (such as CSS files, images, things under \fI\%MEDIA_URL\fP and so forth). If
1328 you want to configure Django to serve static media, read
1329 \fI\%How to manage static files (e.g. images, JavaScript, CSS)\fP\&.
1330 .SS Serving with ASGI in development
1331 .sp
1332 Django\(aqs \fBrunserver\fP command provides a WSGI server. In order to run under
1333 ASGI you will need to use an \fI\%ASGI server\fP\&.
1334 The Django Daphne project provides \fI\%Integration with runserver\fP that you can use.
1335 .SS \fBsendtestemail\fP
1336 .INDENT 0.0
1337 .TP
1338 .B django\-admin sendtestemail [email [email ...]]
1339 .UNINDENT
1340 .sp
1341 Sends a test email (to confirm email sending through Django is working) to the
1342 recipient(s) specified. For example:
1343 .INDENT 0.0
1344 .INDENT 3.5
1345 .sp
1346 .EX
1347 django\-admin sendtestemail [email protected] [email protected]
1348 .EE
1349 .UNINDENT
1350 .UNINDENT
1351 .sp
1352 There are a couple of options, and you may use any combination of them
1353 together:
1354 .INDENT 0.0
1355 .TP
1356 .B \-\-managers
1357 .UNINDENT
1358 .sp
1359 Mails the email addresses specified in \fI\%MANAGERS\fP using
1360 \fI\%mail_managers()\fP\&.
1361 .INDENT 0.0
1362 .TP
1363 .B \-\-admins
1364 .UNINDENT
1365 .sp
1366 Mails the email addresses specified in \fI\%ADMINS\fP using
1367 \fI\%mail_admins()\fP\&.
1368 .SS \fBshell\fP
1369 .INDENT 0.0
1370 .TP
1371 .B django\-admin shell
1372 .UNINDENT
1373 .sp
1374 Starts the Python interactive interpreter.
1375 .sp
1376 All models from installed apps are automatically imported into the shell
1377 environment. Models from apps listed earlier in \fI\%INSTALLED_APPS\fP take
1378 precedence. For a \fB\-\-verbosity\fP of 2 or higher, the automatically imported
1379 objects will be listed. To disable automatic importing entirely, use the
1380 \fB\-\-no\-imports\fP flag.
1381 .sp
1382 See the guide on \fI\%customizing this behaviour\fP to add or remove automatic imports.
1383 .sp
1384 Automatic models import was added.
1385
1386 .INDENT 0.0
1387 .TP
1388 .B \-\-interface {ipython,bpython,python}, \-i {ipython,bpython,python}
1389 .UNINDENT
1390 .sp
1391 Specifies the shell to use. By default, Django will use \X'tty: link https://ipython.org/'\fI\%IPython\fP\X'tty: link' or \X'tty: link https://bpython-interpreter.org/'\fI\%bpython\fP\X'tty: link' if
1392 either is installed. If both are installed, specify which one you want like so:
1393 .sp
1394 IPython:
1395 .INDENT 0.0
1396 .INDENT 3.5
1397 .sp
1398 .EX
1399 django\-admin shell \-i ipython
1400 .EE
1401 .UNINDENT
1402 .UNINDENT
1403 .sp
1404 bpython:
1405 .INDENT 0.0
1406 .INDENT 3.5
1407 .sp
1408 .EX
1409 django\-admin shell \-i bpython
1410 .EE
1411 .UNINDENT
1412 .UNINDENT
1413 .sp
1414 If you have a \(dqrich\(dq shell installed but want to force use of the \(dqplain\(dq
1415 Python interpreter, use \fBpython\fP as the interface name, like so:
1416 .INDENT 0.0
1417 .INDENT 3.5
1418 .sp
1419 .EX
1420 django\-admin shell \-i python
1421 .EE
1422 .UNINDENT
1423 .UNINDENT
1424 .INDENT 0.0
1425 .TP
1426 .B \-\-no\-startup
1427 .UNINDENT
1428 .sp
1429 Disables reading the startup script for the \(dqplain\(dq Python interpreter. By
1430 default, the script pointed to by the \X'tty: link https://docs.python.org/3/using/cmdline.html#envvar-PYTHONSTARTUP'\fI\%PYTHONSTARTUP\fP\X'tty: link' environment
1431 variable or the \fB~/.pythonrc.py\fP script is read.
1432 .INDENT 0.0
1433 .TP
1434 .B \-\-no\-imports
1435 .UNINDENT
1436 .sp
1437
1438 .sp
1439 Disables the automatic import of models from \fI\%INSTALLED_APPS\fP\&.
1440 .INDENT 0.0
1441 .TP
1442 .B \-\-command COMMAND, \-c COMMAND
1443 .UNINDENT
1444 .sp
1445 Lets you pass a command as a string to execute it as Django, like so:
1446 .INDENT 0.0
1447 .INDENT 3.5
1448 .sp
1449 .EX
1450 django\-admin shell \-\-command=\(dqimport django; print(django.__version__)\(dq
1451 .EE
1452 .UNINDENT
1453 .UNINDENT
1454 .sp
1455 You can also pass code in on standard input to execute it. For example:
1456 .INDENT 0.0
1457 .INDENT 3.5
1458 .sp
1459 .EX
1460 $ django\-admin shell <<EOF
1461 > import django
1462 > print(django.__version__)
1463 > EOF
1464 .EE
1465 .UNINDENT
1466 .UNINDENT
1467 .sp
1468 On Windows, the REPL is output due to implementation limits of
1469 \X'tty: link https://docs.python.org/3/library/select.html#select.select'\fI\%select.select()\fP\X'tty: link' on that platform.
1470 .SS \fBshowmigrations\fP
1471 .INDENT 0.0
1472 .TP
1473 .B django\-admin showmigrations [app_label [app_label ...]]
1474 .UNINDENT
1475 .sp
1476 Shows all migrations in a project. You can choose from one of two formats:
1477 .INDENT 0.0
1478 .TP
1479 .B \-\-list, \-l
1480 .UNINDENT
1481 .sp
1482 Lists all of the apps Django knows about, the migrations available for each
1483 app, and whether or not each migration is applied (marked by an \fB[X]\fP next to
1484 the migration name). For a \fB\-\-verbosity\fP of 2 and above, the applied
1485 datetimes are also shown.
1486 .sp
1487 Apps without migrations are also listed, but have \fB(no migrations)\fP printed
1488 under them.
1489 .sp
1490 This is the default output format.
1491 .INDENT 0.0
1492 .TP
1493 .B \-\-plan, \-p
1494 .UNINDENT
1495 .sp
1496 Shows the migration plan Django will follow to apply migrations. Like
1497 \fB\-\-list\fP, applied migrations are marked by an \fB[X]\fP\&. For a \fB\-\-verbosity\fP
1498 of 2 and above, all dependencies of a migration will also be shown.
1499 .sp
1500 \fBapp_label\fPs arguments limit the output, however, dependencies of provided
1501 apps may also be included.
1502 .INDENT 0.0
1503 .TP
1504 .B \-\-database DATABASE
1505 .UNINDENT
1506 .sp
1507 Specifies the database to examine. Defaults to \fBdefault\fP\&.
1508 .SS \fBsqlflush\fP
1509 .INDENT 0.0
1510 .TP
1511 .B django\-admin sqlflush
1512 .UNINDENT
1513 .sp
1514 Prints the SQL statements that would be executed for the \fI\%flush\fP
1515 command.
1516 .INDENT 0.0
1517 .TP
1518 .B \-\-database DATABASE
1519 .UNINDENT
1520 .sp
1521 Specifies the database for which to print the SQL. Defaults to \fBdefault\fP\&.
1522 .SS \fBsqlmigrate\fP
1523 .INDENT 0.0
1524 .TP
1525 .B django\-admin sqlmigrate app_label migration_name
1526 .UNINDENT
1527 .sp
1528 Prints the SQL for the named migration. This requires an active database
1529 connection, which it will use to resolve constraint names; this means you must
1530 generate the SQL against a copy of the database you wish to later apply it on.
1531 .sp
1532 Note that \fBsqlmigrate\fP doesn\(aqt colorize its output.
1533 .INDENT 0.0
1534 .TP
1535 .B \-\-backwards
1536 .UNINDENT
1537 .sp
1538 Generates the SQL for unapplying the migration. By default, the SQL created is
1539 for running the migration in the forwards direction.
1540 .INDENT 0.0
1541 .TP
1542 .B \-\-database DATABASE
1543 .UNINDENT
1544 .sp
1545 Specifies the database for which to generate the SQL. Defaults to \fBdefault\fP\&.
1546 .SS \fBsqlsequencereset\fP
1547 .INDENT 0.0
1548 .TP
1549 .B django\-admin sqlsequencereset app_label [app_label ...]
1550 .UNINDENT
1551 .sp
1552 Prints the SQL statements for resetting sequences for the given app name(s).
1553 .sp
1554 Sequences are indexes used by some database engines to track the next available
1555 number for automatically incremented fields.
1556 .sp
1557 Use this command to generate SQL which will fix cases where a sequence is out
1558 of sync with its automatically incremented field data.
1559 .INDENT 0.0
1560 .TP
1561 .B \-\-database DATABASE
1562 .UNINDENT
1563 .sp
1564 Specifies the database for which to print the SQL. Defaults to \fBdefault\fP\&.
1565 .SS \fBsquashmigrations\fP
1566 .INDENT 0.0
1567 .TP
1568 .B django\-admin squashmigrations app_label [start_migration_name] migration_name
1569 .UNINDENT
1570 .sp
1571 Squashes the migrations for \fBapp_label\fP up to and including \fBmigration_name\fP
1572 down into fewer migrations, if possible. The resulting squashed migrations
1573 can live alongside the unsquashed ones safely. For more information,
1574 please read \fI\%Squashing migrations\fP\&.
1575 .sp
1576 When \fBstart_migration_name\fP is given, Django will only include migrations
1577 starting from and including this migration. This helps to mitigate the
1578 squashing limitation of \fI\%RunPython\fP and
1579 \fI\%django.db.migrations.operations.RunSQL\fP migration operations.
1580 .INDENT 0.0
1581 .TP
1582 .B \-\-no\-optimize
1583 .UNINDENT
1584 .sp
1585 Disables the optimizer when generating a squashed migration. By default, Django
1586 will try to optimize the operations in your migrations to reduce the size of
1587 the resulting file. Use this option if this process is failing or creating
1588 incorrect migrations, though please also file a Django bug report about the
1589 behavior, as optimization is meant to be safe.
1590 .INDENT 0.0
1591 .TP
1592 .B \-\-noinput, \-\-no\-input
1593 .UNINDENT
1594 .sp
1595 Suppresses all user prompts.
1596 .INDENT 0.0
1597 .TP
1598 .B \-\-squashed\-name SQUASHED_NAME
1599 .UNINDENT
1600 .sp
1601 Sets the name of the squashed migration. When omitted, the name is based on the
1602 first and last migration, with \fB_squashed_\fP in between.
1603 .INDENT 0.0
1604 .TP
1605 .B \-\-no\-header
1606 .UNINDENT
1607 .sp
1608 Generate squashed migration file without Django version and timestamp header.
1609 .SS \fBstartapp\fP
1610 .INDENT 0.0
1611 .TP
1612 .B django\-admin startapp name [directory]
1613 .UNINDENT
1614 .sp
1615 Creates a Django app directory structure for the given app name in the current
1616 directory or the given destination.
1617 .sp
1618 By default, \X'tty: link https://github.com/django/django/blob/main/django/conf/app_template'\fI\%the new directory\fP\X'tty: link' contains a
1619 \fBmodels.py\fP file and other app template files. If only the app name is given,
1620 the app directory will be created in the current working directory.
1621 .sp
1622 If the optional destination is provided, Django will use that existing
1623 directory rather than creating a new one. You can use \(aq.\(aq to denote the current
1624 working directory.
1625 .sp
1626 For example:
1627 .INDENT 0.0
1628 .INDENT 3.5
1629 .sp
1630 .EX
1631 django\-admin startapp myapp /Users/jezdez/Code/myapp
1632 .EE
1633 .UNINDENT
1634 .UNINDENT
1635 .INDENT 0.0
1636 .TP
1637 .B \-\-template TEMPLATE
1638 .UNINDENT
1639 .sp
1640 Provides the path to a directory with a custom app template file, or a path to
1641 an uncompressed archive (\fB\&.tar\fP) or a compressed archive (\fB\&.tar.gz\fP,
1642 \fB\&.tar.bz2\fP, \fB\&.tar.xz\fP, \fB\&.tar.lzma\fP, \fB\&.tgz\fP, \fB\&.tbz2\fP, \fB\&.txz\fP,
1643 \fB\&.tlz\fP, \fB\&.zip\fP) containing the app template files.
1644 .sp
1645 For example, this would look for an app template in the given directory when
1646 creating the \fBmyapp\fP app:
1647 .INDENT 0.0
1648 .INDENT 3.5
1649 .sp
1650 .EX
1651 django\-admin startapp \-\-template=/Users/jezdez/Code/my_app_template myapp
1652 .EE
1653 .UNINDENT
1654 .UNINDENT
1655 .sp
1656 Django will also accept URLs (\fBhttp\fP, \fBhttps\fP, \fBftp\fP) to compressed
1657 archives with the app template files, downloading and extracting them on the
1658 fly.
1659 .sp
1660 For example, taking advantage of GitHub\(aqs feature to expose repositories as
1661 zip files, you can use a URL like:
1662 .INDENT 0.0
1663 .INDENT 3.5
1664 .sp
1665 .EX
1666 django\-admin startapp \-\-template=https://github.com/githubuser/django\-app\-template/archive/main.zip myapp
1667 .EE
1668 .UNINDENT
1669 .UNINDENT
1670 .INDENT 0.0
1671 .TP
1672 .B \-\-extension EXTENSIONS, \-e EXTENSIONS
1673 .UNINDENT
1674 .sp
1675 Specifies which file extensions in the app template should be rendered with the
1676 template engine. Defaults to \fBpy\fP\&.
1677 .INDENT 0.0
1678 .TP
1679 .B \-\-name FILES, \-n FILES
1680 .UNINDENT
1681 .sp
1682 Specifies which files in the app template (in addition to those matching
1683 \fB\-\-extension\fP) should be rendered with the template engine. Defaults to an
1684 empty list.
1685 .INDENT 0.0
1686 .TP
1687 .B \-\-exclude DIRECTORIES, \-x DIRECTORIES
1688 .UNINDENT
1689 .sp
1690 Specifies which directories in the app template should be excluded, in addition
1691 to \fB\&.git\fP and \fB__pycache__\fP\&. If this option is not provided, directories
1692 named \fB__pycache__\fP or starting with \fB\&.\fP will be excluded.
1693 .sp
1694 The \fI\%template context\fP used for all matching
1695 files is:
1696 .INDENT 0.0
1697 .IP \(bu 2
1698 Any option passed to the \fBstartapp\fP command (among the command\(aqs supported
1699 options)
1700 .IP \(bu 2
1701 \fBapp_name\fP \-\- the app name as passed to the command
1702 .IP \(bu 2
1703 \fBapp_directory\fP \-\- the full path of the newly created app
1704 .IP \(bu 2
1705 \fBcamel_case_app_name\fP \-\- the app name in camel case format
1706 .IP \(bu 2
1707 \fBdocs_version\fP \-\- the version of the documentation: \fB\(aqdev\(aq\fP or \fB\(aq1.x\(aq\fP
1708 .IP \(bu 2
1709 \fBdjango_version\fP \-\- the version of Django, e.g. \fB\(aq2.0.3\(aq\fP
1710 .UNINDENT
1711 .sp
1712 \fBWARNING:\fP
1713 .INDENT 0.0
1714 .INDENT 3.5
1715 When the app template files are rendered with the Django template
1716 engine (by default all \fB*.py\fP files), Django will also replace all
1717 stray template variables contained. For example, if one of the Python files
1718 contains a docstring explaining a particular feature related
1719 to template rendering, it might result in an incorrect example.
1720 .sp
1721 To work around this problem, you can use the \fI\%templatetag\fP
1722 template tag to \(dqescape\(dq the various parts of the template syntax.
1723 .sp
1724 In addition, to allow Python template files that contain Django template
1725 language syntax while also preventing packaging systems from trying to
1726 byte\-compile invalid \fB*.py\fP files, template files ending with \fB\&.py\-tpl\fP
1727 will be renamed to \fB\&.py\fP\&.
1728 .UNINDENT
1729 .UNINDENT
1730 .sp
1731 \fBWARNING:\fP
1732 .INDENT 0.0
1733 .INDENT 3.5
1734 The contents of custom app (or project) templates should always be
1735 audited before use: Such templates define code that will become
1736 part of your project, and this means that such code will be trusted
1737 as much as any app you install, or code you write yourself.
1738 Further, even rendering the templates is, effectively, executing
1739 code that was provided as input to the management command. The
1740 Django template language may provide wide access into the system,
1741 so make sure any custom template you use is worthy of your trust.
1742 .UNINDENT
1743 .UNINDENT
1744 .SS \fBstartproject\fP
1745 .INDENT 0.0
1746 .TP
1747 .B django\-admin startproject name [directory]
1748 .UNINDENT
1749 .sp
1750 Creates a Django project directory structure for the given project name in
1751 the current directory or the given destination.
1752 .sp
1753 By default, \X'tty: link https://github.com/django/django/blob/main/django/conf/project_template'\fI\%the new directory\fP\X'tty: link' contains
1754 \fBmanage.py\fP and a project package (containing a \fBsettings.py\fP and other
1755 files).
1756 .sp
1757 If only the project name is given, both the project directory and project
1758 package will be named \fB<projectname>\fP and the project directory
1759 will be created in the current working directory.
1760 .sp
1761 If the optional destination is provided, Django will use that existing
1762 directory as the project directory, and create \fBmanage.py\fP and the project
1763 package within it. Use \(aq.\(aq to denote the current working directory.
1764 .sp
1765 For example:
1766 .INDENT 0.0
1767 .INDENT 3.5
1768 .sp
1769 .EX
1770 django\-admin startproject myproject /Users/jezdez/Code/myproject_repo
1771 .EE
1772 .UNINDENT
1773 .UNINDENT
1774 .INDENT 0.0
1775 .TP
1776 .B \-\-template TEMPLATE
1777 .UNINDENT
1778 .sp
1779 Specifies a directory, file path, or URL of a custom project template. See the
1780 \fI\%startapp \-\-template\fP documentation for examples and usage.
1781 .INDENT 0.0
1782 .TP
1783 .B \-\-extension EXTENSIONS, \-e EXTENSIONS
1784 .UNINDENT
1785 .sp
1786 Specifies which file extensions in the project template should be rendered with
1787 the template engine. Defaults to \fBpy\fP\&.
1788 .INDENT 0.0
1789 .TP
1790 .B \-\-name FILES, \-n FILES
1791 .UNINDENT
1792 .sp
1793 Specifies which files in the project template (in addition to those matching
1794 \fB\-\-extension\fP) should be rendered with the template engine. Defaults to an
1795 empty list.
1796 .INDENT 0.0
1797 .TP
1798 .B \-\-exclude DIRECTORIES, \-x DIRECTORIES
1799 .UNINDENT
1800 .sp
1801 Specifies which directories in the project template should be excluded, in
1802 addition to \fB\&.git\fP and \fB__pycache__\fP\&. If this option is not provided,
1803 directories named \fB__pycache__\fP or starting with \fB\&.\fP will be excluded.
1804 .sp
1805 The \fI\%template context\fP used is:
1806 .INDENT 0.0
1807 .IP \(bu 2
1808 Any option passed to the \fBstartproject\fP command (among the command\(aqs
1809 supported options)
1810 .IP \(bu 2
1811 \fBproject_name\fP \-\- the project name as passed to the command
1812 .IP \(bu 2
1813 \fBproject_directory\fP \-\- the full path of the newly created project
1814 .IP \(bu 2
1815 \fBsecret_key\fP \-\- a random key for the \fI\%SECRET_KEY\fP setting
1816 .IP \(bu 2
1817 \fBdocs_version\fP \-\- the version of the documentation: \fB\(aqdev\(aq\fP or \fB\(aq1.x\(aq\fP
1818 .IP \(bu 2
1819 \fBdjango_version\fP \-\- the version of Django, e.g. \fB\(aq2.0.3\(aq\fP
1820 .UNINDENT
1821 .sp
1822 Please also see the \fI\%rendering warning\fP and
1823 \fI\%trusted code warning\fP as mentioned for
1824 \fI\%startapp\fP\&.
1825 .SS \fBtest\fP
1826 .INDENT 0.0
1827 .TP
1828 .B django\-admin test [test_label [test_label ...]]
1829 .UNINDENT
1830 .sp
1831 Runs tests for all installed apps. See \fI\%Testing in Django\fP for more
1832 information.
1833 .INDENT 0.0
1834 .TP
1835 .B \-\-failfast
1836 .UNINDENT
1837 .sp
1838 Stops running tests and reports the failure immediately after a test fails.
1839 .INDENT 0.0
1840 .TP
1841 .B \-\-testrunner TESTRUNNER
1842 .UNINDENT
1843 .sp
1844 Controls the test runner class that is used to execute tests. This value
1845 overrides the value provided by the \fI\%TEST_RUNNER\fP setting.
1846 .INDENT 0.0
1847 .TP
1848 .B \-\-noinput, \-\-no\-input
1849 .UNINDENT
1850 .sp
1851 Suppresses all user prompts. A typical prompt is a warning about deleting an
1852 existing test database.
1853 .SS Test runner options
1854 .sp
1855 The \fBtest\fP command receives options on behalf of the specified
1856 \fI\%\-\-testrunner\fP\&. These are the options of the default test runner:
1857 \fI\%DiscoverRunner\fP\&.
1858 .INDENT 0.0
1859 .TP
1860 .B \-\-keepdb
1861 .UNINDENT
1862 .sp
1863 Preserves the test database between test runs. This has the advantage of
1864 skipping both the create and destroy actions which can greatly decrease the
1865 time to run tests, especially those in a large test suite. If the test database
1866 does not exist, it will be created on the first run and then preserved for each
1867 subsequent run. Unless the \fI\%MIGRATE\fP test setting is
1868 \fBFalse\fP, any unapplied migrations will also be applied to the test database
1869 before running the test suite.
1870 .INDENT 0.0
1871 .TP
1872 .B \-\-shuffle [SEED]
1873 .UNINDENT
1874 .sp
1875 Randomizes the order of tests before running them. This can help detect tests
1876 that aren\(aqt properly isolated. The test order generated by this option is a
1877 deterministic function of the integer seed given. When no seed is passed, a
1878 seed is chosen randomly and printed to the console. To repeat a particular test
1879 order, pass a seed. The test orders generated by this option preserve Django\(aqs
1880 \fI\%guarantees on test order\fP\&. They also keep tests grouped
1881 by test case class.
1882 .sp
1883 The shuffled orderings also have a special consistency property useful when
1884 narrowing down isolation issues. Namely, for a given seed and when running a
1885 subset of tests, the new order will be the original shuffling restricted to the
1886 smaller set. Similarly, when adding tests while keeping the seed the same, the
1887 order of the original tests will be the same in the new order.
1888 .INDENT 0.0
1889 .TP
1890 .B \-\-reverse, \-r
1891 .UNINDENT
1892 .sp
1893 Sorts test cases in the opposite execution order. This may help in debugging
1894 the side effects of tests that aren\(aqt properly isolated. \fI\%Grouping by test
1895 class\fP is preserved when using this option. This can be used
1896 in conjunction with \fB\-\-shuffle\fP to reverse the order for a particular seed.
1897 .INDENT 0.0
1898 .TP
1899 .B \-\-debug\-mode
1900 .UNINDENT
1901 .sp
1902 Sets the \fI\%DEBUG\fP setting to \fBTrue\fP prior to running tests. This may
1903 help troubleshoot test failures.
1904 .INDENT 0.0
1905 .TP
1906 .B \-\-debug\-sql, \-d
1907 .UNINDENT
1908 .sp
1909 Enables \fI\%SQL logging\fP for failing tests. If
1910 \fB\-\-verbosity\fP is \fB2\fP, then queries in passing tests are also output.
1911 .INDENT 0.0
1912 .TP
1913 .B \-\-parallel [N]
1914 .UNINDENT
1915 .INDENT 0.0
1916 .TP
1917 .B DJANGO_TEST_PROCESSES
1918 .UNINDENT
1919 .sp
1920 Runs tests in separate parallel processes. Since modern processors have
1921 multiple cores, this allows running tests significantly faster.
1922 .sp
1923 Using \fB\-\-parallel\fP without a value, or with the value \fBauto\fP, runs one test
1924 process per core according to \X'tty: link https://docs.python.org/3/library/multiprocessing.html#multiprocessing.cpu_count'\fI\%multiprocessing.cpu_count()\fP\X'tty: link'\&. You can
1925 override this by passing the desired number of processes, e.g.
1926 \fB\-\-parallel 4\fP, or by setting the \fI\%DJANGO_TEST_PROCESSES\fP environment
1927 variable.
1928 .sp
1929 Django distributes test cases — \X'tty: link https://docs.python.org/3/library/unittest.html#unittest.TestCase'\fI\%unittest.TestCase\fP\X'tty: link' subclasses — to
1930 subprocesses. If there are fewer test case classes than configured processes,
1931 Django will reduce the number of processes accordingly.
1932 .sp
1933 Each process gets its own database. You must ensure that different test case
1934 classes don\(aqt access the same resources. For instance, test case classes that
1935 touch the filesystem should create a temporary directory for their own use.
1936 .sp
1937 \fBNOTE:\fP
1938 .INDENT 0.0
1939 .INDENT 3.5
1940 If you have test classes that cannot be run in parallel, you can use
1941 \fBSerializeMixin\fP to run them sequentially. See \fI\%Enforce running test
1942 classes sequentially\fP\&.
1943 .UNINDENT
1944 .UNINDENT
1945 .sp
1946 This option requires the third\-party \fBtblib\fP package to display tracebacks
1947 correctly:
1948 .INDENT 0.0
1949 .INDENT 3.5
1950 .sp
1951 .EX
1952 $ python \-m pip install tblib
1953 .EE
1954 .UNINDENT
1955 .UNINDENT
1956 .sp
1957 This feature isn\(aqt available on Windows. It doesn\(aqt work with the Oracle
1958 database backend either.
1959 .sp
1960 If you want to use \X'tty: link https://docs.python.org/3/library/pdb.html#module-pdb'\fI\%pdb\fP\X'tty: link' while debugging tests, you must disable parallel
1961 execution (\fB\-\-parallel=1\fP). You\(aqll see something like \fBbdb.BdbQuit\fP if you
1962 don\(aqt.
1963 .sp
1964 \fBWARNING:\fP
1965 .INDENT 0.0
1966 .INDENT 3.5
1967 When test parallelization is enabled and a test fails, Django may be
1968 unable to display the exception traceback. This can make debugging
1969 difficult. If you encounter this problem, run the affected test without
1970 parallelization to see the traceback of the failure.
1971 .sp
1972 This is a known limitation. It arises from the need to serialize objects
1973 in order to exchange them between processes. See
1974 \X'tty: link https://docs.python.org/3/library/pickle.html#pickle-picklable'\fI\%What can be pickled and unpickled?\fP\X'tty: link' for details.
1975 .UNINDENT
1976 .UNINDENT
1977 .INDENT 0.0
1978 .TP
1979 .B \-\-tag TAGS
1980 .UNINDENT
1981 .sp
1982 Runs only tests \fI\%marked with the specified tags\fP\&.
1983 May be specified multiple times and combined with \fI\%test \-\-exclude\-tag\fP\&.
1984 .sp
1985 Tests that fail to load are always considered matching.
1986 .INDENT 0.0
1987 .TP
1988 .B \-\-exclude\-tag EXCLUDE_TAGS
1989 .UNINDENT
1990 .sp
1991 Excludes tests \fI\%marked with the specified tags\fP\&.
1992 May be specified multiple times and combined with \fI\%test \-\-tag\fP\&.
1993 .INDENT 0.0
1994 .TP
1995 .B \-k TEST_NAME_PATTERNS
1996 .UNINDENT
1997 .sp
1998 Runs test methods and classes matching test name patterns, in the same way as
1999 \X'tty: link https://docs.python.org/3/library/unittest.html#cmdoption-unittest-k'\fI\%unittest\(aqs \-k option\fP\X'tty: link'\&. Can be specified multiple times.
2000 .INDENT 0.0
2001 .TP
2002 .B \-\-pdb
2003 .UNINDENT
2004 .sp
2005 Spawns a \fBpdb\fP debugger at each test error or failure. If you have it
2006 installed, \fBipdb\fP is used instead.
2007 .INDENT 0.0
2008 .TP
2009 .B \-\-buffer, \-b
2010 .UNINDENT
2011 .sp
2012 Discards output (\fBstdout\fP and \fBstderr\fP) for passing tests, in the same way
2013 as \X'tty: link https://docs.python.org/3/library/unittest.html#cmdoption-unittest-b'\fI\%unittest\(aqs \-\-buffer option\fP\X'tty: link'\&.
2014 .INDENT 0.0
2015 .TP
2016 .B \-\-no\-faulthandler
2017 .UNINDENT
2018 .sp
2019 Django automatically calls \X'tty: link https://docs.python.org/3/library/faulthandler.html#faulthandler.enable'\fI\%faulthandler.enable()\fP\X'tty: link' when starting the
2020 tests, which allows it to print a traceback if the interpreter crashes. Pass
2021 \fB\-\-no\-faulthandler\fP to disable this behavior.
2022 .INDENT 0.0
2023 .TP
2024 .B \-\-timing
2025 .UNINDENT
2026 .sp
2027 Outputs timings, including database setup and total run time.
2028 .INDENT 0.0
2029 .TP
2030 .B \-\-durations N
2031 .UNINDENT
2032 .sp
2033 Shows the N slowest test cases (N=0 for all).
2034 .INDENT 0.0
2035 .INDENT 3.5
2036 .IP "Python 3.12 and later"
2037 .sp
2038 This feature is only available for Python 3.12 and later.
2039 .UNINDENT
2040 .UNINDENT
2041 .SS \fBtestserver\fP
2042 .INDENT 0.0
2043 .TP
2044 .B django\-admin testserver [fixture [fixture ...]]
2045 .UNINDENT
2046 .sp
2047 Runs a Django development server (as in \fI\%runserver\fP) using data from
2048 the given fixture(s).
2049 .sp
2050 For example, this command:
2051 .INDENT 0.0
2052 .INDENT 3.5
2053 .sp
2054 .EX
2055 django\-admin testserver mydata.json
2056 .EE
2057 .UNINDENT
2058 .UNINDENT
2059 .sp
2060 \&...would perform the following steps:
2061 .INDENT 0.0
2062 .IP 1. 3
2063 Create a test database, as described in \fI\%The test database\fP\&.
2064 .IP 2. 3
2065 Populate the test database with fixture data from the given fixtures.
2066 (For more on fixtures, see the documentation for \fI\%loaddata\fP above.)
2067 .IP 3. 3
2068 Runs the Django development server (as in \fI\%runserver\fP), pointed at
2069 this newly created test database instead of your production database.
2070 .UNINDENT
2071 .sp
2072 This is useful in a number of ways:
2073 .INDENT 0.0
2074 .IP \(bu 2
2075 When you\(aqre writing \fI\%unit tests\fP of how your views
2076 act with certain fixture data, you can use \fBtestserver\fP to interact with
2077 the views in a web browser, manually.
2078 .IP \(bu 2
2079 Let\(aqs say you\(aqre developing your Django application and have a \(dqpristine\(dq
2080 copy of a database that you\(aqd like to interact with. You can dump your
2081 database to a \fI\%fixture\fP (using the
2082 \fI\%dumpdata\fP command, explained above), then use \fBtestserver\fP to run
2083 your web application with that data. With this arrangement, you have the
2084 flexibility of messing up your data in any way, knowing that whatever data
2085 changes you\(aqre making are only being made to a test database.
2086 .UNINDENT
2087 .sp
2088 Note that this server does \fInot\fP automatically detect changes to your Python
2089 source code (as \fI\%runserver\fP does). It does, however, detect changes to
2090 templates.
2091 .INDENT 0.0
2092 .TP
2093 .B \-\-addrport ADDRPORT
2094 .UNINDENT
2095 .sp
2096 Specifies a different port, or IP address and port, from the default of
2097 \fB127.0.0.1:8000\fP\&. This value follows exactly the same format and serves
2098 exactly the same function as the argument to the \fI\%runserver\fP command.
2099 .sp
2100 Examples:
2101 .sp
2102 To run the test server on port 7000 with \fBfixture1\fP and \fBfixture2\fP:
2103 .INDENT 0.0
2104 .INDENT 3.5
2105 .sp
2106 .EX
2107 django\-admin testserver \-\-addrport 7000 fixture1 fixture2
2108 django\-admin testserver fixture1 fixture2 \-\-addrport 7000
2109 .EE
2110 .UNINDENT
2111 .UNINDENT
2112 .sp
2113 (The above statements are equivalent. We include both of them to demonstrate
2114 that it doesn\(aqt matter whether the options come before or after the fixture
2115 arguments.)
2116 .sp
2117 To run on 1.2.3.4:7000 with a \fBtest\fP fixture:
2118 .INDENT 0.0
2119 .INDENT 3.5
2120 .sp
2121 .EX
2122 django\-admin testserver \-\-addrport 1.2.3.4:7000 test
2123 .EE
2124 .UNINDENT
2125 .UNINDENT
2126 .INDENT 0.0
2127 .TP
2128 .B \-\-noinput, \-\-no\-input
2129 .UNINDENT
2130 .sp
2131 Suppresses all user prompts. A typical prompt is a warning about deleting an
2132 existing test database.
2133 .SH COMMANDS PROVIDED BY APPLICATIONS
2134 .sp
2135 Some commands are only available when the \fBdjango.contrib\fP application that
2136 \fI\%implements\fP them has been
2137 \fI\%enabled\fP\&. This section describes them grouped by
2138 their application.
2139 .SS \fBdjango.contrib.auth\fP
2140 .SS \fBchangepassword\fP
2141 .INDENT 0.0
2142 .TP
2143 .B django\-admin changepassword [<username>]
2144 .UNINDENT
2145 .sp
2146 This command is only available if Django\(aqs \fI\%authentication system\fP (\fBdjango.contrib.auth\fP) is installed.
2147 .sp
2148 Allows changing a user\(aqs password. It prompts you to enter a new password twice
2149 for the given user. If the entries are identical, this immediately becomes the
2150 new password. If you do not supply a user, the command will attempt to change
2151 the password whose username matches the current user.
2152 .INDENT 0.0
2153 .TP
2154 .B \-\-database DATABASE
2155 .UNINDENT
2156 .sp
2157 Specifies the database to query for the user. Defaults to \fBdefault\fP\&.
2158 .sp
2159 Example usage:
2160 .INDENT 0.0
2161 .INDENT 3.5
2162 .sp
2163 .EX
2164 django\-admin changepassword ringo
2165 .EE
2166 .UNINDENT
2167 .UNINDENT
2168 .SS \fBcreatesuperuser\fP
2169 .INDENT 0.0
2170 .TP
2171 .B django\-admin createsuperuser
2172 .UNINDENT
2173 .INDENT 0.0
2174 .TP
2175 .B DJANGO_SUPERUSER_PASSWORD
2176 .UNINDENT
2177 .sp
2178 This command is only available if Django\(aqs \fI\%authentication system\fP (\fBdjango.contrib.auth\fP) is installed.
2179 .sp
2180 Creates a superuser account (a user who has all permissions). This is
2181 useful if you need to create an initial superuser account or if you need to
2182 programmatically generate superuser accounts for your site(s).
2183 .sp
2184 When run interactively, this command will prompt for a password for
2185 the new superuser account. When run non\-interactively, you can provide
2186 a password by setting the \fI\%DJANGO_SUPERUSER_PASSWORD\fP environment
2187 variable. Otherwise, no password will be set, and the superuser account will
2188 not be able to log in until a password has been manually set for it.
2189 .sp
2190 In non\-interactive mode, the
2191 \fI\%USERNAME_FIELD\fP and required
2192 fields (listed in
2193 \fI\%REQUIRED_FIELDS\fP) fall back to
2194 \fBDJANGO_SUPERUSER_<uppercase_field_name>\fP environment variables, unless they
2195 are overridden by a command line argument. For example, to provide an \fBemail\fP
2196 field, you can use \fBDJANGO_SUPERUSER_EMAIL\fP environment variable.
2197 .INDENT 0.0
2198 .TP
2199 .B \-\-noinput, \-\-no\-input
2200 .UNINDENT
2201 .sp
2202 Suppresses all user prompts. If a suppressed prompt cannot be resolved
2203 automatically, the command will exit with error code 1.
2204 .INDENT 0.0
2205 .TP
2206 .B \-\-username USERNAME
2207 .UNINDENT
2208 .INDENT 0.0
2209 .TP
2210 .B \-\-email EMAIL
2211 .UNINDENT
2212 .sp
2213 The username and email address for the new account can be supplied by
2214 using the \fB\-\-username\fP and \fB\-\-email\fP arguments on the command
2215 line. If either of those is not supplied, \fBcreatesuperuser\fP will prompt for
2216 it when running interactively.
2217 .INDENT 0.0
2218 .TP
2219 .B \-\-database DATABASE
2220 .UNINDENT
2221 .sp
2222 Specifies the database into which the superuser object will be saved.
2223 .sp
2224 You can subclass the management command and override \fBget_input_data()\fP if you
2225 want to customize data input and validation. Consult the source code for
2226 details on the existing implementation and the method\(aqs parameters. For example,
2227 it could be useful if you have a \fBForeignKey\fP in
2228 \fI\%REQUIRED_FIELDS\fP and want to
2229 allow creating an instance instead of entering the primary key of an existing
2230 instance.
2231 .SS \fBdjango.contrib.contenttypes\fP
2232 .SS \fBremove_stale_contenttypes\fP
2233 .INDENT 0.0
2234 .TP
2235 .B django\-admin remove_stale_contenttypes
2236 .UNINDENT
2237 .sp
2238 This command is only available if Django\(aqs \fI\%contenttypes app\fP (\fI\%django.contrib.contenttypes\fP) is installed.
2239 .sp
2240 Deletes stale content types (from deleted models) in your database. Any objects
2241 that depend on the deleted content types will also be deleted. A list of
2242 deleted objects will be displayed before you confirm it\(aqs okay to proceed with
2243 the deletion.
2244 .INDENT 0.0
2245 .TP
2246 .B \-\-database DATABASE
2247 .UNINDENT
2248 .sp
2249 Specifies the database to use. Defaults to \fBdefault\fP\&.
2250 .INDENT 0.0
2251 .TP
2252 .B \-\-include\-stale\-apps
2253 .UNINDENT
2254 .sp
2255 Deletes stale content types including ones from previously installed apps that
2256 have been removed from \fI\%INSTALLED_APPS\fP\&. Defaults to \fBFalse\fP\&.
2257 .SS \fBdjango.contrib.gis\fP
2258 .SS \fBogrinspect\fP
2259 .sp
2260 This command is only available if \fI\%GeoDjango\fP
2261 (\fBdjango.contrib.gis\fP) is installed.
2262 .sp
2263 Please refer to its \fI\%description\fP in the GeoDjango
2264 documentation.
2265 .SS \fBdjango.contrib.sessions\fP
2266 .SS \fBclearsessions\fP
2267 .INDENT 0.0
2268 .TP
2269 .B django\-admin clearsessions
2270 .UNINDENT
2271 .sp
2272 Can be run as a cron job or directly to clean out expired sessions.
2273 .SS \fBdjango.contrib.staticfiles\fP
2274 .SS \fBcollectstatic\fP
2275 .sp
2276 This command is only available if the \fI\%static files application\fP (\fBdjango.contrib.staticfiles\fP) is installed.
2277 .sp
2278 Please refer to its \fI\%description\fP in the
2279 \fI\%staticfiles\fP documentation.
2280 .SS \fBfindstatic\fP
2281 .sp
2282 This command is only available if the \fI\%static files application\fP (\fBdjango.contrib.staticfiles\fP) is installed.
2283 .sp
2284 Please refer to its \fI\%description\fP in the \fI\%staticfiles\fP documentation.
2285 .SH DEFAULT OPTIONS
2286 .sp
2287 Although some commands may allow their own custom options, every command
2288 allows for the following options by default:
2289 .INDENT 0.0
2290 .TP
2291 .B \-\-pythonpath PYTHONPATH
2292 .UNINDENT
2293 .sp
2294 Adds the given filesystem path to the Python \X'tty: link https://docs.python.org/3/library/sys.html#sys.path'\fI\%sys.path\fP\X'tty: link' module
2295 attribute. If this isn\(aqt provided, \fBdjango\-admin\fP will use the
2296 \X'tty: link https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH'\fI\%PYTHONPATH\fP\X'tty: link' environment variable.
2297 .sp
2298 This option is unnecessary in \fBmanage.py\fP, because it takes care of setting
2299 the Python path for you.
2300 .sp
2301 Example usage:
2302 .INDENT 0.0
2303 .INDENT 3.5
2304 .sp
2305 .EX
2306 django\-admin migrate \-\-pythonpath=\(aq/home/djangoprojects/myproject\(aq
2307 .EE
2308 .UNINDENT
2309 .UNINDENT
2310 .INDENT 0.0
2311 .TP
2312 .B \-\-settings SETTINGS
2313 .UNINDENT
2314 .sp
2315 Specifies the settings module to use. The settings module should be in Python
2316 package syntax, e.g. \fBmysite.settings\fP\&. If this isn\(aqt provided,
2317 \fBdjango\-admin\fP will use the \fI\%DJANGO_SETTINGS_MODULE\fP environment
2318 variable.
2319 .sp
2320 This option is unnecessary in \fBmanage.py\fP, because it uses
2321 \fBsettings.py\fP from the current project by default.
2322 .sp
2323 Example usage:
2324 .INDENT 0.0
2325 .INDENT 3.5
2326 .sp
2327 .EX
2328 django\-admin migrate \-\-settings=mysite.settings
2329 .EE
2330 .UNINDENT
2331 .UNINDENT
2332 .INDENT 0.0
2333 .TP
2334 .B \-\-traceback
2335 .UNINDENT
2336 .sp
2337 Displays a full stack trace when a \fI\%CommandError\fP
2338 is raised. By default, \fBdjango\-admin\fP will show an error message when a
2339 \fBCommandError\fP occurs and a full stack trace for any other exception.
2340 .sp
2341 This option is ignored by \fI\%runserver\fP\&.
2342 .sp
2343 Example usage:
2344 .INDENT 0.0
2345 .INDENT 3.5
2346 .sp
2347 .EX
2348 django\-admin migrate \-\-traceback
2349 .EE
2350 .UNINDENT
2351 .UNINDENT
2352 .INDENT 0.0
2353 .TP
2354 .B \-\-verbosity {0,1,2,3}, \-v {0,1,2,3}
2355 .UNINDENT
2356 .sp
2357 Specifies the amount of notification and debug information that a command
2358 should print to the console.
2359 .INDENT 0.0
2360 .IP \(bu 2
2361 \fB0\fP means no output.
2362 .IP \(bu 2
2363 \fB1\fP means normal output (default).
2364 .IP \(bu 2
2365 \fB2\fP means verbose output.
2366 .IP \(bu 2
2367 \fB3\fP means \fIvery\fP verbose output.
2368 .UNINDENT
2369 .sp
2370 This option is ignored by \fI\%runserver\fP\&.
2371 .sp
2372 Example usage:
2373 .INDENT 0.0
2374 .INDENT 3.5
2375 .sp
2376 .EX
2377 django\-admin migrate \-\-verbosity 2
2378 .EE
2379 .UNINDENT
2380 .UNINDENT
2381 .INDENT 0.0
2382 .TP
2383 .B \-\-no\-color
2384 .UNINDENT
2385 .sp
2386 Disables colorized command output. Some commands format their output to be
2387 colorized. For example, errors will be printed to the console in red and SQL
2388 statements will be syntax highlighted.
2389 .sp
2390 Example usage:
2391 .INDENT 0.0
2392 .INDENT 3.5
2393 .sp
2394 .EX
2395 django\-admin runserver \-\-no\-color
2396 .EE
2397 .UNINDENT
2398 .UNINDENT
2399 .INDENT 0.0
2400 .TP
2401 .B \-\-force\-color
2402 .UNINDENT
2403 .sp
2404 Forces colorization of the command output if it would otherwise be disabled
2405 as discussed in \fI\%Syntax coloring\fP\&. For example, you may want to pipe
2406 colored output to another command.
2407 .INDENT 0.0
2408 .TP
2409 .B \-\-skip\-checks
2410 .UNINDENT
2411 .sp
2412 Skips running system checks prior to running the command. This option is only
2413 available if the
2414 \fI\%requires_system_checks\fP command
2415 attribute is not an empty list or tuple.
2416 .sp
2417 Example usage:
2418 .INDENT 0.0
2419 .INDENT 3.5
2420 .sp
2421 .EX
2422 django\-admin migrate \-\-skip\-checks
2423 .EE
2424 .UNINDENT
2425 .UNINDENT
2426 .SH EXTRA NICETIES
2427 .SS Syntax coloring
2428 .INDENT 0.0
2429 .TP
2430 .B DJANGO_COLORS
2431 .UNINDENT
2432 .sp
2433 The \fBdjango\-admin\fP / \fBmanage.py\fP commands will use pretty
2434 color\-coded output if your terminal supports ANSI\-colored output. It
2435 won\(aqt use the color codes if you\(aqre piping the command\(aqs output to
2436 another program unless the \fI\%\-\-force\-color\fP option is used.
2437 .SS Windows support
2438 .sp
2439 On Windows 10, the \X'tty: link https://www.microsoft.com/en-us/p/windows-terminal-preview/9n0dx20hk701'\fI\%Windows Terminal\fP\X'tty: link' application, \X'tty: link https://code.visualstudio.com'\fI\%VS Code\fP\X'tty: link', and PowerShell
2440 (where virtual terminal processing is enabled) allow colored output, and are
2441 supported by default.
2442 .sp
2443 Under Windows, the legacy \fBcmd.exe\fP native console doesn\(aqt support ANSI
2444 escape sequences so by default there is no color output. In this case either of
2445 two third\-party libraries are needed:
2446 .INDENT 0.0
2447 .IP \(bu 2
2448 Install \X'tty: link https://pypi.org/project/colorama/'\fI\%colorama\fP\X'tty: link', a Python package that translates ANSI color codes
2449 into Windows API calls. Django commands will detect its presence and will
2450 make use of its services to color output just like on Unix\-based platforms.
2451 \fBcolorama\fP can be installed via pip:
2452 .INDENT 2.0
2453 .INDENT 3.5
2454 .sp
2455 .EX
2456 \&...\e> py \-m pip install \(dqcolorama >= 0.4.6\(dq
2457 .EE
2458 .UNINDENT
2459 .UNINDENT
2460 .IP \(bu 2
2461 Install \X'tty: link http://adoxa.altervista.org/ansicon/'\fI\%ANSICON\fP\X'tty: link', a third\-party tool that allows \fBcmd.exe\fP to process
2462 ANSI color codes. Django commands will detect its presence and will make use
2463 of its services to color output just like on Unix\-based platforms.
2464 .UNINDENT
2465 .sp
2466 Other modern terminal environments on Windows, that support terminal colors,
2467 but which are not automatically detected as supported by Django, may \(dqfake\(dq the
2468 installation of \fBANSICON\fP by setting the appropriate environmental variable,
2469 \fBANSICON=\(dqon\(dq\fP\&.
2470 .SS Custom colors
2471 .sp
2472 The colors used for syntax highlighting can be customized. Django
2473 ships with three color palettes:
2474 .INDENT 0.0
2475 .IP \(bu 2
2476 \fBdark\fP, suited to terminals that show white text on a black
2477 background. This is the default palette.
2478 .IP \(bu 2
2479 \fBlight\fP, suited to terminals that show black text on a white
2480 background.
2481 .IP \(bu 2
2482 \fBnocolor\fP, which disables syntax highlighting.
2483 .UNINDENT
2484 .sp
2485 You select a palette by setting a \fI\%DJANGO_COLORS\fP environment
2486 variable to specify the palette you want to use. For example, to
2487 specify the \fBlight\fP palette under a Unix or OS/X BASH shell, you
2488 would run the following at a command prompt:
2489 .INDENT 0.0
2490 .INDENT 3.5
2491 .sp
2492 .EX
2493 export DJANGO_COLORS=\(dqlight\(dq
2494 .EE
2495 .UNINDENT
2496 .UNINDENT
2497 .sp
2498 You can also customize the colors that are used. Django specifies a
2499 number of roles in which color is used:
2500 .INDENT 0.0
2501 .IP \(bu 2
2502 \fBerror\fP \- A major error.
2503 .IP \(bu 2
2504 \fBnotice\fP \- A minor error.
2505 .IP \(bu 2
2506 \fBsuccess\fP \- A success.
2507 .IP \(bu 2
2508 \fBwarning\fP \- A warning.
2509 .IP \(bu 2
2510 \fBsql_field\fP \- The name of a model field in SQL.
2511 .IP \(bu 2
2512 \fBsql_coltype\fP \- The type of a model field in SQL.
2513 .IP \(bu 2
2514 \fBsql_keyword\fP \- An SQL keyword.
2515 .IP \(bu 2
2516 \fBsql_table\fP \- The name of a model in SQL.
2517 .IP \(bu 2
2518 \fBhttp_info\fP \- A 1XX HTTP Informational server response.
2519 .IP \(bu 2
2520 \fBhttp_success\fP \- A 2XX HTTP Success server response.
2521 .IP \(bu 2
2522 \fBhttp_not_modified\fP \- A 304 HTTP Not Modified server response.
2523 .IP \(bu 2
2524 \fBhttp_redirect\fP \- A 3XX HTTP Redirect server response other than 304.
2525 .IP \(bu 2
2526 \fBhttp_not_found\fP \- A 404 HTTP Not Found server response.
2527 .IP \(bu 2
2528 \fBhttp_bad_request\fP \- A 4XX HTTP Bad Request server response other than 404.
2529 .IP \(bu 2
2530 \fBhttp_server_error\fP \- A 5XX HTTP Server Error response.
2531 .IP \(bu 2
2532 \fBmigrate_heading\fP \- A heading in a migrations management command.
2533 .IP \(bu 2
2534 \fBmigrate_label\fP \- A migration name.
2535 .UNINDENT
2536 .sp
2537 Each of these roles can be assigned a specific foreground and
2538 background color, from the following list:
2539 .INDENT 0.0
2540 .IP \(bu 2
2541 \fBblack\fP
2542 .IP \(bu 2
2543 \fBred\fP
2544 .IP \(bu 2
2545 \fBgreen\fP
2546 .IP \(bu 2
2547 \fByellow\fP
2548 .IP \(bu 2
2549 \fBblue\fP
2550 .IP \(bu 2
2551 \fBmagenta\fP
2552 .IP \(bu 2
2553 \fBcyan\fP
2554 .IP \(bu 2
2555 \fBwhite\fP
2556 .UNINDENT
2557 .sp
2558 Each of these colors can then be modified by using the following
2559 display options:
2560 .INDENT 0.0
2561 .IP \(bu 2
2562 \fBbold\fP
2563 .IP \(bu 2
2564 \fBunderscore\fP
2565 .IP \(bu 2
2566 \fBblink\fP
2567 .IP \(bu 2
2568 \fBreverse\fP
2569 .IP \(bu 2
2570 \fBconceal\fP
2571 .UNINDENT
2572 .sp
2573 A color specification follows one of the following patterns:
2574 .INDENT 0.0
2575 .IP \(bu 2
2576 \fBrole=fg\fP
2577 .IP \(bu 2
2578 \fBrole=fg/bg\fP
2579 .IP \(bu 2
2580 \fBrole=fg,option,option\fP
2581 .IP \(bu 2
2582 \fBrole=fg/bg,option,option\fP
2583 .UNINDENT
2584 .sp
2585 where \fBrole\fP is the name of a valid color role, \fBfg\fP is the
2586 foreground color, \fBbg\fP is the background color and each \fBoption\fP
2587 is one of the color modifying options. Multiple color specifications
2588 are then separated by a semicolon. For example:
2589 .INDENT 0.0
2590 .INDENT 3.5
2591 .sp
2592 .EX
2593 export DJANGO_COLORS=\(dqerror=yellow/blue,blink;notice=magenta\(dq
2594 .EE
2595 .UNINDENT
2596 .UNINDENT
2597 .sp
2598 would specify that errors be displayed using blinking yellow on blue,
2599 and notices displayed using magenta. All other color roles would be
2600 left uncolored.
2601 .sp
2602 Colors can also be specified by extending a base palette. If you put
2603 a palette name in a color specification, all the colors implied by that
2604 palette will be loaded. So:
2605 .INDENT 0.0
2606 .INDENT 3.5
2607 .sp
2608 .EX
2609 export DJANGO_COLORS=\(dqlight;error=yellow/blue,blink;notice=magenta\(dq
2610 .EE
2611 .UNINDENT
2612 .UNINDENT
2613 .sp
2614 would specify the use of all the colors in the light color palette,
2615 \fIexcept\fP for the colors for errors and notices which would be
2616 overridden as specified.
2617 .SS Bash completion
2618 .sp
2619 If you use the Bash shell, consider installing the Django bash completion
2620 script, which lives in \X'tty: link https://github.com/django/django/blob/main/extras/django_bash_completion'\fI\%extras/django_bash_completion\fP\X'tty: link' in the Django source
2621 distribution. It enables tab\-completion of \fBdjango\-admin\fP and
2622 \fBmanage.py\fP commands, so you can, for instance...
2623 .INDENT 0.0
2624 .IP \(bu 2
2625 Type \fBdjango\-admin\fP\&.
2626 .IP \(bu 2
2627 Press [TAB] to see all available options.
2628 .IP \(bu 2
2629 Type \fBsql\fP, then [TAB], to see all available options whose names start
2630 with \fBsql\fP\&.
2631 .UNINDENT
2632 .sp
2633 See \fI\%How to create custom django\-admin commands\fP for how to add customized actions.
2634 .SS Black formatting
2635 .sp
2636 The Python files created by \fI\%startproject\fP, \fI\%startapp\fP,
2637 \fI\%optimizemigration\fP, \fI\%makemigrations\fP, and
2638 \fI\%squashmigrations\fP are formatted using the \fBblack\fP command if it is
2639 present on your \fBPATH\fP\&.
2640 .sp
2641 If you have \fBblack\fP globally installed, but do not wish it used for the
2642 current project, you can set the \fBPATH\fP explicitly:
2643 .INDENT 0.0
2644 .INDENT 3.5
2645 .sp
2646 .EX
2647 PATH=path/to/venv/bin django\-admin makemigrations
2648 .EE
2649 .UNINDENT
2650 .UNINDENT
2651 .sp
2652 For commands using \fBstdout\fP you can pipe the output to \fBblack\fP if needed:
2653 .INDENT 0.0
2654 .INDENT 3.5
2655 .sp
2656 .EX
2657 django\-admin inspectdb | black \-
2658 .EE
2659 .UNINDENT
2660 .UNINDENT
2661 .INDENT 0.0
2662 .TP
2663 .B django.core.management.call_command(name, *args, **options)
2664 .UNINDENT
2665 .sp
2666 To call a management command from code use \fBcall_command()\fP\&.
2667 .INDENT 0.0
2668 .TP
2669 .B \fBname\fP
2670 the name of the command to call or a command object. Passing the name is
2671 preferred unless the object is required for testing.
2672 .TP
2673 .B \fB*args\fP
2674 a list of arguments accepted by the command. Arguments are passed to the
2675 argument parser, so you can use the same style as you would on the command
2676 line. For example, \fBcall_command(\(aqflush\(aq, \(aq\-\-verbosity=0\(aq)\fP\&.
2677 .TP
2678 .B \fB**options\fP
2679 named options accepted on the command\-line. Options are passed to the command
2680 without triggering the argument parser, which means you\(aqll need to pass the
2681 correct type. For example, \fBcall_command(\(aqflush\(aq, verbosity=0)\fP (zero must
2682 be an integer rather than a string).
2683 .UNINDENT
2684 .sp
2685 Examples:
2686 .INDENT 0.0
2687 .INDENT 3.5
2688 .sp
2689 .EX
2690 from django.core import management
2691 from django.core.management.commands import loaddata
2692
2693 management.call_command(\(dqflush\(dq, verbosity=0, interactive=False)
2694 management.call_command(\(dqloaddata\(dq, \(dqtest_data\(dq, verbosity=0)
2695 management.call_command(loaddata.Command(), \(dqtest_data\(dq, verbosity=0)
2696 .EE
2697 .UNINDENT
2698 .UNINDENT
2699 .sp
2700 Note that command options that take no arguments are passed as keywords
2701 with \fBTrue\fP or \fBFalse\fP, as you can see with the \fBinteractive\fP option above.
2702 .sp
2703 Named arguments can be passed by using either one of the following syntaxes:
2704 .INDENT 0.0
2705 .INDENT 3.5
2706 .sp
2707 .EX
2708 # Similar to the command line
2709 management.call_command(\(dqdumpdata\(dq, \(dq\-\-natural\-foreign\(dq)
2710
2711 # Named argument similar to the command line minus the initial dashes and
2712 # with internal dashes replaced by underscores
2713 management.call_command(\(dqdumpdata\(dq, natural_foreign=True)
2714
2715 # \(gause_natural_foreign_keys\(ga is the option destination variable
2716 management.call_command(\(dqdumpdata\(dq, use_natural_foreign_keys=True)
2717 .EE
2718 .UNINDENT
2719 .UNINDENT
2720 .sp
2721 Some command options have different names when using \fBcall_command()\fP instead
2722 of \fBdjango\-admin\fP or \fBmanage.py\fP\&. For example, \fBdjango\-admin
2723 createsuperuser \-\-no\-input\fP translates to \fBcall_command(\(aqcreatesuperuser\(aq,
2724 interactive=False)\fP\&. To find what keyword argument name to use for
2725 \fBcall_command()\fP, check the command\(aqs source code for the \fBdest\fP argument
2726 passed to \fBparser.add_argument()\fP\&.
2727 .sp
2728 Command options which take multiple options are passed a list:
2729 .INDENT 0.0
2730 .INDENT 3.5
2731 .sp
2732 .EX
2733 management.call_command(\(dqdumpdata\(dq, exclude=[\(dqcontenttypes\(dq, \(dqauth\(dq])
2734 .EE
2735 .UNINDENT
2736 .UNINDENT
2737 .sp
2738 The return value of the \fBcall_command()\fP function is the same as the return
2739 value of the \fBhandle()\fP method of the command.
2740 .SH OUTPUT REDIRECTION
2741 .sp
2742 Note that you can redirect standard output and error streams as all commands
2743 support the \fBstdout\fP and \fBstderr\fP options. For example, you could write:
2744 .INDENT 0.0
2745 .INDENT 3.5
2746 .sp
2747 .EX
2748 with open(\(dq/path/to/command_output\(dq, \(dqw\(dq) as f:
2749 management.call_command(\(dqdumpdata\(dq, stdout=f)
2750 .EE
2751 .UNINDENT
2752 .UNINDENT
2753 .SH AUTHOR
2754 Django Software Foundation
2755 .SH COPYRIGHT
2756 Django Software Foundation and contributors
2757 .\" Generated by docutils manpage writer.
2758 .