Debian Codegraph @

docs/ref/django-admin.txt

raw
1 ==================================
2 ``django-admin`` and ``manage.py``
3 ==================================
4
5 ``django-admin`` is Django's command-line utility for administrative tasks.
6 This document outlines all it can do.
7
8 In addition, ``manage.py`` is automatically created in each Django project. It
9 does the same thing as ``django-admin`` but also sets the
10 :envvar:`DJANGO_SETTINGS_MODULE` environment variable so that it points to your
11 project's ``settings.py`` file.
12
13 The ``django-admin`` script should be on your system path if you installed
14 Django via ``pip``. If it's not in your path, ensure you have your virtual
15 environment activated.
16
17 Generally, when working on a single Django project, it's easier to use
18 ``manage.py`` than ``django-admin``. If you need to switch between multiple
19 Django settings files, use ``django-admin`` with
20 :envvar:`DJANGO_SETTINGS_MODULE` or the :option:`--settings` command line
21 option.
22
23 The command-line examples throughout this document use ``django-admin`` to
24 be consistent, but any example can use ``manage.py`` or ``python -m django``
25 just as well.
26
27 Usage
28 =====
29
30 .. console::
31
32 $ django-admin <command> [options]
33 $ manage.py <command> [options]
34 $ python -m django <command> [options]
35
36 ``command`` should be one of the commands listed in this document.
37 ``options``, which is optional, should be zero or more of the options available
38 for the given command.
39
40 Getting runtime help
41 --------------------
42
43 .. django-admin:: help
44
45 Run ``django-admin help`` to display usage information and a list of the
46 commands provided by each application.
47
48 Run ``django-admin help --commands`` to display a list of all available
49 commands.
50
51 Run ``django-admin help <command>`` to display a description of the given
52 command and a list of its available options.
53
54 App names
55 ---------
56
57 Many commands take a list of "app names." An "app name" is the basename of
58 the package containing your models. For example, if your :setting:`INSTALLED_APPS`
59 contains the string ``'mysite.blog'``, the app name is ``blog``.
60
61 Determining the version
62 -----------------------
63
64 .. django-admin:: version
65
66 Run ``django-admin version`` to display the current Django version.
67
68 The output follows the schema described in :pep:`440`:
69
70 .. code-block:: text
71
72 1.4.dev17026
73 1.4a1
74 1.4
75
76 Displaying debug output
77 -----------------------
78
79 .. program:: None
80
81 Use :option:`--verbosity`, where it is supported, to specify the amount of
82 notification and debug information that ``django-admin`` prints to the console.
83
84 Available commands
85 ==================
86
87 ``check``
88 ---------
89
90 .. django-admin:: check [app_label [app_label ...]]
91
92 Uses the :doc:`system check framework </ref/checks>` to inspect the entire
93 Django project for common problems.
94
95 By default, all apps will be checked. You can check a subset of apps by
96 providing a list of app labels as arguments:
97
98 .. console::
99
100 django-admin check auth admin myapp
101
102 .. django-admin-option:: --tag TAGS, -t TAGS
103
104 The system check framework performs many different types of checks that are
105 :ref:`categorized with tags <system-check-builtin-tags>`. You can use these
106 tags to restrict the checks performed to just those in a particular category.
107 For example, to perform only models and compatibility checks, run:
108
109 .. console::
110
111 django-admin check --tag models --tag compatibility
112
113 .. django-admin-option:: --database DATABASE
114
115 Specifies the database to run checks requiring database access:
116
117 .. console::
118
119 django-admin check --database default --database other
120
121 By default, these checks will not be run.
122
123 .. django-admin-option:: --list-tags
124
125 Lists all available tags.
126
127 .. django-admin-option:: --deploy
128
129 Activates some additional checks that are only relevant in a deployment setting.
130
131 You can use this option in your local development environment, but since your
132 local development settings module may not have many of your production settings,
133 you will probably want to point the ``check`` command at a different settings
134 module, either by setting the :envvar:`DJANGO_SETTINGS_MODULE` environment
135 variable, or by passing the ``--settings`` option:
136
137 .. console::
138
139 django-admin check --deploy --settings=production_settings
140
141 Or you could run it directly on a production or staging deployment to verify
142 that the correct settings are in use (omitting ``--settings``). You could even
143 make it part of your integration test suite.
144
145 .. django-admin-option:: --fail-level {CRITICAL,ERROR,WARNING,INFO,DEBUG}
146
147 Specifies the message level that will cause the command to exit with a non-zero
148 status. Default is ``ERROR``.
149
150 ``compilemessages``
151 -------------------
152
153 .. django-admin:: compilemessages
154
155 Compiles ``.po`` files created by :djadmin:`makemessages` to ``.mo`` files for
156 use with the built-in gettext support. See :doc:`/topics/i18n/index`.
157
158 .. django-admin-option:: --locale LOCALE, -l LOCALE
159
160 Specifies the locale(s) to process. If not provided, all locales are processed.
161
162 .. django-admin-option:: --exclude EXCLUDE, -x EXCLUDE
163
164 Specifies the locale(s) to exclude from processing. If not provided, no locales
165 are excluded.
166
167 .. django-admin-option:: --use-fuzzy, -f
168
169 Includes `fuzzy translations`_ into compiled files.
170
171 Example usage:
172
173 .. console::
174
175 django-admin compilemessages --locale=pt_BR
176 django-admin compilemessages --locale=pt_BR --locale=fr -f
177 django-admin compilemessages -l pt_BR
178 django-admin compilemessages -l pt_BR -l fr --use-fuzzy
179 django-admin compilemessages --exclude=pt_BR
180 django-admin compilemessages --exclude=pt_BR --exclude=fr
181 django-admin compilemessages -x pt_BR
182 django-admin compilemessages -x pt_BR -x fr
183
184 .. _fuzzy translations: https://www.gnu.org/software/gettext/manual/html_node/Fuzzy-Entries.html
185
186 .. django-admin-option:: --ignore PATTERN, -i PATTERN
187
188 Ignores directories matching the given :mod:`glob`-style pattern. Use
189 multiple times to ignore more.
190
191 Example usage:
192
193 .. console::
194
195 django-admin compilemessages --ignore=cache --ignore=outdated/*/locale
196
197 ``createcachetable``
198 --------------------
199
200 .. django-admin:: createcachetable
201
202 Creates the cache tables for use with the database cache backend using the
203 information from your settings file. See :doc:`/topics/cache` for more
204 information.
205
206 .. django-admin-option:: --database DATABASE
207
208 Specifies the database in which the cache table(s) will be created. Defaults to
209 ``default``.
210
211 .. django-admin-option:: --dry-run
212
213 Prints the SQL that would be run without actually running it, so you can
214 customize it or use the migrations framework.
215
216 ``dbshell``
217 -----------
218
219 .. django-admin:: dbshell
220
221 Runs the command-line client for the database engine specified in your
222 :setting:`ENGINE <DATABASE-ENGINE>` setting, with the connection parameters
223 specified in your :setting:`USER`, :setting:`PASSWORD`, etc., settings.
224
225 * For PostgreSQL, this runs the ``psql`` command-line client.
226 * For MySQL, this runs the ``mysql`` command-line client.
227 * For SQLite, this runs the ``sqlite3`` command-line client.
228 * For Oracle, this runs the ``sqlplus`` command-line client.
229
230 This command assumes the programs are on your ``PATH`` so that a call to
231 the program name (``psql``, ``mysql``, ``sqlite3``, ``sqlplus``) will find the
232 program in the right place. There's no way to specify the location of the
233 program manually.
234
235 .. django-admin-option:: --database DATABASE
236
237 Specifies the database onto which to open a shell. Defaults to ``default``.
238
239 .. django-admin-option:: -- ARGUMENTS
240
241 Any arguments following a ``--`` divider will be passed on to the underlying
242 command-line client. For example, with PostgreSQL you can use the ``psql``
243 command's ``-c`` flag to execute a raw SQL query directly:
244
245 .. console::
246
247 $ django-admin dbshell -- -c 'select current_user'
248 current_user
249 --------------
250 postgres
251 (1 row)
252
253 On MySQL/MariaDB, you can do this with the ``mysql`` command's ``-e`` flag:
254
255 .. console::
256
257 $ django-admin dbshell -- -e "select user()"
258 +----------------------+
259 | user() |
260 +----------------------+
261 | djangonaut@localhost |
262 +----------------------+
263
264 .. note::
265
266 Be aware that not all options set in the :setting:`OPTIONS` part of your
267 database configuration in :setting:`DATABASES` are passed to the
268 command-line client, e.g. ``'isolation_level'``.
269
270 ``diffsettings``
271 ----------------
272
273 .. django-admin:: diffsettings
274
275 Displays differences between the current settings file and Django's default
276 settings (or another settings file specified by :option:`--default`).
277
278 Settings that don't appear in the defaults are followed by ``"###"``. For
279 example, the default settings don't define :setting:`ROOT_URLCONF`, so
280 :setting:`ROOT_URLCONF` is followed by ``"###"`` in the output of
281 ``diffsettings``.
282
283 .. django-admin-option:: --all
284
285 Displays all settings, even if they have Django's default value. Such settings
286 are prefixed by ``"###"``.
287
288 .. django-admin-option:: --default MODULE
289
290 The settings module to compare the current settings against. Leave empty to
291 compare against Django's default settings.
292
293 .. django-admin-option:: --output {hash,unified}
294
295 Specifies the output format. Available values are ``hash`` and ``unified``.
296 ``hash`` is the default mode that displays the output that's described above.
297 ``unified`` displays the output similar to ``diff -u``. Default settings are
298 prefixed with a minus sign, followed by the changed setting prefixed with a
299 plus sign.
300
301 ``dumpdata``
302 ------------
303
304 .. django-admin:: dumpdata [app_label[.ModelName] [app_label[.ModelName] ...]]
305
306 Outputs to standard output all data in the database associated with the named
307 application(s).
308
309 If no application name is provided, all installed applications will be dumped.
310
311 The output of ``dumpdata`` can be used as input for :djadmin:`loaddata`.
312
313 When result of ``dumpdata`` is saved as a file, it can serve as a
314 :ref:`fixture <fixtures-explanation>` for
315 :ref:`tests <topics-testing-fixtures>` or as an
316 :ref:`initial data <initial-data-via-fixtures>`.
317
318 Note that ``dumpdata`` uses the default manager on the model for selecting the
319 records to dump. If you're using a :ref:`custom manager <custom-managers>` as
320 the default manager and it filters some of the available records, not all of the
321 objects will be dumped.
322
323 .. django-admin-option:: --all, -a
324
325 Uses Django's base manager, dumping records which might otherwise be filtered
326 or modified by a custom manager.
327
328 .. django-admin-option:: --format FORMAT
329
330 Specifies the serialization format of the output. Defaults to JSON. Supported
331 formats are listed in :ref:`serialization-formats`.
332
333 .. django-admin-option:: --indent INDENT
334
335 Specifies the number of indentation spaces to use in the output. Defaults to
336 ``None`` which displays all data on single line.
337
338 .. django-admin-option:: --exclude EXCLUDE, -e EXCLUDE
339
340 Prevents specific applications or models (specified in the form of
341 ``app_label.ModelName``) from being dumped. If you specify a model name, then
342 only that model will be excluded, rather than the entire application. You can
343 also mix application names and model names.
344
345 If you want to exclude multiple applications, pass ``--exclude`` more than
346 once:
347
348 .. console::
349
350 django-admin dumpdata --exclude=auth --exclude=contenttypes
351
352 .. django-admin-option:: --database DATABASE
353
354 Specifies the database from which data will be dumped. Defaults to ``default``.
355
356 .. django-admin-option:: --natural-foreign
357
358 Uses the ``natural_key()`` model method to serialize any foreign key and
359 many-to-many relationship to objects of the type that defines the method. If
360 you're dumping ``contrib.auth`` ``Permission`` objects or
361 ``contrib.contenttypes`` ``ContentType`` objects, you should probably use this
362 flag. See the :ref:`natural keys <topics-serialization-natural-keys>`
363 documentation for more details on this and the next option.
364
365 .. django-admin-option:: --natural-primary
366
367 Omits the primary key in the serialized data of this object since it can be
368 calculated during deserialization.
369
370 .. django-admin-option:: --pks PRIMARY_KEYS
371
372 Outputs only the objects specified by a comma separated list of primary keys.
373 This is only available when dumping one model. By default, all the records of
374 the model are output.
375
376 .. django-admin-option:: --output OUTPUT, -o OUTPUT
377
378 Specifies a file to write the serialized data to. By default, the data goes to
379 standard output.
380
381 When this option is set and ``--verbosity`` is greater than 0 (the default), a
382 progress bar is shown in the terminal.
383
384 Fixtures compression
385 ~~~~~~~~~~~~~~~~~~~~
386
387 The output file can be compressed with one of the ``bz2``, ``gz``, ``lzma``, or
388 ``xz`` formats by ending the filename with the corresponding extension.
389 For example, to output the data as a compressed JSON file:
390
391 .. console::
392
393 django-admin dumpdata -o mydata.json.gz
394
395 ``flush``
396 ---------
397
398 .. django-admin:: flush
399
400 Removes all data from the database and re-executes any post-synchronization
401 handlers. The table of which migrations have been applied is not cleared.
402
403 If you would rather start from an empty database and rerun all migrations, you
404 should drop and recreate the database and then run :djadmin:`migrate` instead.
405
406 .. django-admin-option:: --noinput, --no-input
407
408 Suppresses all user prompts.
409
410 .. django-admin-option:: --database DATABASE
411
412 Specifies the database to flush. Defaults to ``default``.
413
414 ``inspectdb``
415 -------------
416
417 .. django-admin:: inspectdb [table [table ...]]
418
419 Introspects the database tables in the database pointed-to by the
420 :setting:`NAME` setting and outputs a Django model module (a ``models.py``
421 file) to standard output.
422
423 You may choose what tables or views to inspect by passing their names as
424 arguments. If no arguments are provided, models are created for views only if
425 the :option:`--include-views` option is used. Models for partition tables are
426 created on PostgreSQL if the :option:`--include-partitions` option is used.
427
428 Use this if you have a legacy database with which you'd like to use Django.
429 The script will inspect the database and create a model for each table within
430 it.
431
432 As you might expect, the created models will have an attribute for every field
433 in the table. Note that ``inspectdb`` has a few special cases in its field-name
434 output:
435
436 * If ``inspectdb`` cannot map a column's type to a model field type, it'll
437 use ``TextField`` and will insert the Python comment
438 ``'This field type is a guess.'`` next to the field in the generated
439 model. The recognized fields may depend on apps listed in
440 :setting:`INSTALLED_APPS`. For example, :mod:`django.contrib.postgres` adds
441 recognition for several PostgreSQL-specific field types.
442
443 * If the database column name is a Python reserved word (such as
444 ``'pass'``, ``'class'`` or ``'for'``), ``inspectdb`` will append
445 ``'_field'`` to the attribute name. For example, if a table has a column
446 ``'for'``, the generated model will have a field ``'for_field'``, with
447 the ``db_column`` attribute set to ``'for'``. ``inspectdb`` will insert
448 the Python comment
449 ``'Field renamed because it was a Python reserved word.'`` next to the
450 field.
451
452 This feature is meant as a shortcut, not as definitive model generation. After
453 you run it, you'll want to look over the generated models yourself to make
454 customizations. In particular, you'll need to rearrange models' order, so that
455 models that refer to other models are ordered properly.
456
457 Django doesn't create database defaults when a
458 :attr:`~django.db.models.Field.default` is specified on a model field.
459 Similarly, database defaults aren't translated to model field defaults or
460 detected in any fashion by ``inspectdb``.
461
462 By default, ``inspectdb`` creates unmanaged models. That is, ``managed = False``
463 in the model's ``Meta`` class tells Django not to manage each table's creation,
464 modification, and deletion. If you do want to allow Django to manage the
465 table's lifecycle, you'll need to change the
466 :attr:`~django.db.models.Options.managed` option to ``True`` (or remove
467 it because ``True`` is its default value).
468
469 Database-specific notes
470 ~~~~~~~~~~~~~~~~~~~~~~~
471
472 Oracle
473 ^^^^^^
474
475 * Models are created for materialized views if :option:`--include-views` is
476 used.
477
478 PostgreSQL
479 ^^^^^^^^^^
480
481 * Models are created for foreign tables.
482 * Models are created for materialized views if
483 :option:`--include-views` is used.
484 * Models are created for partition tables if
485 :option:`--include-partitions` is used.
486
487 .. django-admin-option:: --database DATABASE
488
489 Specifies the database to introspect. Defaults to ``default``.
490
491 .. django-admin-option:: --include-partitions
492
493 If this option is provided, models are also created for partitions.
494
495 Only support for PostgreSQL is implemented.
496
497 .. django-admin-option:: --include-views
498
499 If this option is provided, models are also created for database views.
500
501 ``loaddata``
502 ------------
503
504 .. django-admin:: loaddata fixture [fixture ...]
505
506 Searches for and loads the contents of the named
507 :ref:`fixture <fixtures-explanation>` into the database.
508
509 .. django-admin-option:: --database DATABASE
510
511 Specifies the database into which the data will be loaded. Defaults to
512 ``default``.
513
514 .. django-admin-option:: --ignorenonexistent, -i
515
516 Ignores fields and models that may have been removed since the fixture was
517 originally generated.
518
519 .. django-admin-option:: --app APP_LABEL
520
521 Specifies a single app to look for fixtures in rather than looking in all apps.
522
523 .. django-admin-option:: --format FORMAT
524
525 Specifies the :ref:`serialization format <serialization-formats>` (e.g.,
526 ``json`` or ``xml``) for fixtures :ref:`read from stdin
527 <loading-fixtures-stdin>`.
528
529 .. django-admin-option:: --exclude EXCLUDE, -e EXCLUDE
530
531 Excludes loading the fixtures from the given applications and/or models (in the
532 form of ``app_label`` or ``app_label.ModelName``). Use the option multiple
533 times to exclude more than one app or model.
534
535 .. _loading-fixtures-stdin:
536
537 Loading fixtures from ``stdin``
538 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
539
540 You can use a dash as the fixture name to load input from ``sys.stdin``. For
541 example:
542
543 .. console::
544
545 django-admin loaddata --format=json -
546
547 When reading from ``stdin``, the :option:`--format <loaddata --format>` option
548 is required to specify the :ref:`serialization format <serialization-formats>`
549 of the input (e.g., ``json`` or ``xml``).
550
551 Loading from ``stdin`` is useful with standard input and output redirections.
552 For example:
553
554 .. console::
555
556 django-admin dumpdata --format=json --database=test app_label.ModelName | django-admin loaddata --format=json --database=prod -
557
558 The :djadmin:`dumpdata` command can be used to generate input for ``loaddata``.
559
560 .. seealso::
561
562 For more detail about fixtures see the :ref:`fixtures-explanation` topic.
563
564 ``makemessages``
565 ----------------
566
567 .. django-admin:: makemessages
568
569 Runs over the entire source tree of the current directory and pulls out all
570 strings marked for translation. It creates (or updates) a message file in the
571 conf/locale (in the Django tree) or locale (for project and application)
572 directory. After making changes to the messages files you need to compile them
573 with :djadmin:`compilemessages` for use with the builtin gettext support. See
574 the :ref:`i18n documentation <how-to-create-language-files>` for details.
575
576 This command doesn't require configured settings. However, when settings aren't
577 configured, the command can't ignore the :setting:`MEDIA_ROOT` and
578 :setting:`STATIC_ROOT` directories or include :setting:`LOCALE_PATHS`.
579
580 .. django-admin-option:: --all, -a
581
582 Updates the message files for all available languages.
583
584 .. django-admin-option:: --extension EXTENSIONS, -e EXTENSIONS
585
586 Specifies a list of file extensions to examine (default: ``html``, ``txt``,
587 ``py`` or ``js`` if :option:`--domain` is ``djangojs``).
588
589 Example usage:
590
591 .. console::
592
593 django-admin makemessages --locale=de --extension xhtml
594
595 Separate multiple extensions with commas or use ``-e`` or ``--extension``
596 multiple times:
597
598 .. console::
599
600 django-admin makemessages --locale=de --extension=html,txt --extension xml
601
602 .. django-admin-option:: --locale LOCALE, -l LOCALE
603
604 Specifies the locale(s) to process.
605
606 .. django-admin-option:: --exclude EXCLUDE, -x EXCLUDE
607
608 Specifies the locale(s) to exclude from processing. If not provided, no locales
609 are excluded.
610
611 Example usage:
612
613 .. console::
614
615 django-admin makemessages --locale=pt_BR
616 django-admin makemessages --locale=pt_BR --locale=fr
617 django-admin makemessages -l pt_BR
618 django-admin makemessages -l pt_BR -l fr
619 django-admin makemessages --exclude=pt_BR
620 django-admin makemessages --exclude=pt_BR --exclude=fr
621 django-admin makemessages -x pt_BR
622 django-admin makemessages -x pt_BR -x fr
623
624 .. django-admin-option:: --domain DOMAIN, -d DOMAIN
625
626 Specifies the domain of the messages files. Supported options are:
627
628 * ``django`` for all ``*.py``, ``*.html`` and ``*.txt`` files (default)
629 * ``djangojs`` for ``*.js`` files
630
631 .. django-admin-option:: --symlinks, -s
632
633 Follows symlinks to directories when looking for new translation strings.
634
635 Example usage:
636
637 .. console::
638
639 django-admin makemessages --locale=de --symlinks
640
641 .. django-admin-option:: --ignore PATTERN, -i PATTERN
642
643 Ignores files or directories matching the given :mod:`glob`-style pattern. Use
644 multiple times to ignore more.
645
646 These patterns are used by default: ``'CVS'``, ``'.*'``, ``'*~'``, ``'*.pyc'``.
647
648 Example usage:
649
650 .. console::
651
652 django-admin makemessages --locale=en_US --ignore=apps/* --ignore=secret/*.html
653
654 .. django-admin-option:: --no-default-ignore
655
656 Disables the default values of ``--ignore``.
657
658 .. django-admin-option:: --no-wrap
659
660 Disables breaking long message lines into several lines in language files.
661
662 .. django-admin-option:: --no-location
663
664 Suppresses writing '``#: filename:line``’ comment lines in language files.
665 Using this option makes it harder for technically skilled translators to
666 understand each message's context.
667
668 .. django-admin-option:: --add-location [{full,file,never}]
669
670 Controls ``#: filename:line`` comment lines in language files. If the option
671 is:
672
673 * ``full`` (the default if not given): the lines include both file name and
674 line number.
675 * ``file``: the line number is omitted.
676 * ``never``: the lines are suppressed (same as :option:`--no-location`).
677
678 Requires ``gettext`` 0.19 or newer.
679
680 .. django-admin-option:: --no-obsolete
681
682 Removes obsolete message strings from the ``.po`` files.
683
684 .. django-admin-option:: --keep-pot
685
686 Prevents deleting the temporary ``.pot`` files generated before creating the
687 ``.po`` file. This is useful for debugging errors which may prevent the final
688 language files from being created.
689
690 .. seealso::
691
692 See :ref:`customizing-makemessages` for instructions on how to customize
693 the keywords that :djadmin:`makemessages` passes to ``xgettext``.
694
695 ``makemigrations``
696 ------------------
697
698 .. django-admin:: makemigrations [app_label [app_label ...]]
699
700 Creates new migrations based on the changes detected to your models.
701 Migrations, their relationship with apps and more are covered in depth in
702 :doc:`the migrations documentation</topics/migrations>`.
703
704 Providing one or more app names as arguments will limit the migrations created
705 to the app(s) specified and any dependencies needed (the table at the other end
706 of a ``ForeignKey``, for example).
707
708 To add migrations to an app that doesn't have a ``migrations`` directory, run
709 ``makemigrations`` with the app's ``app_label``.
710
711 .. django-admin-option:: --noinput, --no-input
712
713 Suppresses all user prompts. If a suppressed prompt cannot be resolved
714 automatically, the command will exit with error code 3.
715
716 .. django-admin-option:: --empty
717
718 Outputs an empty migration for the specified apps, for manual editing. This is
719 for advanced users and should not be used unless you are familiar with the
720 migration format, migration operations, and the dependencies between your
721 migrations.
722
723 .. django-admin-option:: --dry-run
724
725 Shows what migrations would be made without actually writing any migrations
726 files to disk. Using this option along with ``--verbosity 3`` will also show
727 the complete migrations files that would be written.
728
729 .. django-admin-option:: --merge
730
731 Enables fixing of migration conflicts.
732
733 .. django-admin-option:: --name NAME, -n NAME
734
735 Allows naming the generated migration(s) instead of using a generated name. The
736 name must be a valid Python :ref:`identifier <python:identifiers>`.
737
738 .. django-admin-option:: --no-header
739
740 Generate migration files without Django version and timestamp header.
741
742 .. django-admin-option:: --check
743
744 Makes ``makemigrations`` exit with a non-zero status when model changes without
745 migrations are detected. Implies ``--dry-run``.
746
747 .. django-admin-option:: --scriptable
748
749 Diverts log output and input prompts to ``stderr``, writing only paths of
750 generated migration files to ``stdout``.
751
752 .. django-admin-option:: --update
753
754 Merges model changes into the latest migration and optimize the resulting
755 operations.
756
757 The updated migration will have a generated name. In order to preserve the
758 previous name, set it using ``--name``.
759
760 ``migrate``
761 -----------
762
763 .. django-admin:: migrate [app_label] [migration_name]
764
765 Synchronizes the database state with the current set of models and migrations.
766 Migrations, their relationship with apps and more are covered in depth in
767 :doc:`the migrations documentation</topics/migrations>`.
768
769 The behavior of this command changes depending on the arguments provided:
770
771 * No arguments: All apps have all of their migrations run.
772 * ``<app_label>``: The specified app has its migrations run, up to the most
773 recent migration. This may involve running other apps' migrations too, due
774 to dependencies.
775 * ``<app_label> <migrationname>``: Brings the database schema to a state where
776 the named migration is applied, but no later migrations in the same app are
777 applied. This may involve unapplying migrations if you have previously
778 migrated past the named migration. You can use a prefix of the migration
779 name, e.g. ``0001``, as long as it's unique for the given app name. Use the
780 name ``zero`` to migrate all the way back i.e. to revert all applied
781 migrations for an app.
782
783 .. warning::
784
785 When unapplying migrations, all dependent migrations will also be
786 unapplied, regardless of ``<app_label>``. You can use ``--plan`` to check
787 which migrations will be unapplied.
788
789 .. django-admin-option:: --database DATABASE
790
791 Specifies the database to migrate. Defaults to ``default``.
792
793 .. django-admin-option:: --fake
794
795 Marks the migrations up to the target one (following the rules above) as
796 applied, but without actually running the SQL to change your database schema.
797
798 This is intended for advanced users to manipulate the
799 current migration state directly if they're manually applying changes;
800 be warned that using ``--fake`` runs the risk of putting the migration state
801 table into a state where manual recovery will be needed to make migrations
802 run correctly.
803
804 .. django-admin-option:: --fake-initial
805
806 Allows Django to skip an app's initial migration if all database tables with
807 the names of all models created by all
808 :class:`~django.db.migrations.operations.CreateModel` operations in that
809 migration already exist. This option is intended for use when first running
810 migrations against a database that preexisted the use of migrations. This
811 option does not, however, check for matching database schema beyond matching
812 table names and so is only safe to use if you are confident that your existing
813 schema matches what is recorded in your initial migration.
814
815 .. django-admin-option:: --plan
816
817 Shows the migration operations that will be performed for the given ``migrate``
818 command.
819
820 .. django-admin-option:: --run-syncdb
821
822 Allows creating tables for apps without migrations. While this isn't
823 recommended, the migrations framework is sometimes too slow on large projects
824 with hundreds of models.
825
826 .. django-admin-option:: --noinput, --no-input
827
828 Suppresses all user prompts. An example prompt is asking about removing stale
829 content types.
830
831 .. django-admin-option:: --check
832
833 Makes ``migrate`` exit with a non-zero status when unapplied migrations are
834 detected.
835
836 .. django-admin-option:: --prune
837
838 Deletes nonexistent migrations from the ``django_migrations`` table. This is
839 useful when migration files replaced by a squashed migration have been removed.
840 See :ref:`migration-squashing` for more details.
841
842 ``optimizemigration``
843 ---------------------
844
845 .. django-admin:: optimizemigration app_label migration_name
846
847 Optimizes the operations for the named migration and overrides the existing
848 file. If the migration contains functions that must be manually copied, the
849 command creates a new migration file suffixed with ``_optimized`` that is meant
850 to replace the named migration.
851
852 .. django-admin-option:: --check
853
854 Makes ``optimizemigration`` exit with a non-zero status when a migration can be
855 optimized.
856
857 ``runserver``
858 -------------
859
860 .. django-admin:: runserver [addrport]
861
862 Starts a lightweight development web server on the local machine. By default,
863 the server runs on port 8000 on the IP address ``127.0.0.1``. You can pass in an
864 IP address and port number explicitly.
865
866 If you run this script as a user with normal privileges (recommended), you
867 might not have access to start a port on a low port number. Low port numbers
868 are reserved for the superuser (root).
869
870 This server uses the WSGI application object specified by the
871 :setting:`WSGI_APPLICATION` setting.
872
873 .. warning:: DO NOT USE THIS SERVER IN A PRODUCTION SETTING.
874
875 This lightweight development server has not gone through security audits or
876 performance tests, hence is unsuitable for production. Making this server
877 able to handle a production environment is outside the scope of Django.
878
879 The development server automatically reloads Python code for each request, as
880 needed. You don't need to restart the server for code changes to take effect.
881 However, some actions like adding files don't trigger a restart, so you'll
882 have to restart the server in these cases.
883
884 If you're using Linux or MacOS and install both :pypi:`pywatchman` and the
885 `Watchman`_ service, kernel signals will be used to autoreload the server
886 (rather than polling file modification timestamps each second). This offers
887 better performance on large projects, reduced response time after code changes,
888 more robust change detection, and a reduction in power usage. Django supports
889 ``pywatchman`` 1.2.0 and higher.
890
891 .. admonition:: Large directories with many files may cause performance issues
892
893 When using Watchman with a project that includes large non-Python
894 directories like ``node_modules``, it's advisable to ignore this directory
895 for optimal performance. See the `watchman documentation`_ for information
896 on how to do this.
897
898 .. admonition:: Watchman timeout
899
900 .. envvar:: DJANGO_WATCHMAN_TIMEOUT
901
902 The default timeout of ``Watchman`` client is 5 seconds. You can change it
903 by setting the :envvar:`DJANGO_WATCHMAN_TIMEOUT` environment variable.
904
905 .. _Watchman: https://facebook.github.io/watchman/
906 .. _watchman documentation: https://facebook.github.io/watchman/docs/config#ignore_dirs
907
908 When you start the server, and each time you change Python code while the
909 server is running, the system check framework will check your entire Django
910 project for some common errors (see the :djadmin:`check` command). If any
911 errors are found, they will be printed to standard output. You can use the
912 ``--skip-checks`` option to skip running system checks.
913
914 You can run as many concurrent servers as you want, as long as they're on
915 separate ports by executing ``django-admin runserver`` more than once.
916
917 Note that the default IP address, ``127.0.0.1``, is not accessible from other
918 machines on your network. To make your development server viewable to other
919 machines on the network, use its own IP address (e.g. ``192.168.2.1``), ``0``
920 (shortcut for ``0.0.0.0``), ``0.0.0.0``, or ``::`` (with IPv6 enabled).
921
922 You can provide an IPv6 address surrounded by brackets
923 (e.g. ``[200a::1]:8000``). This will automatically enable IPv6 support.
924
925 A hostname containing ASCII-only characters can also be used.
926
927 If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled
928 (default in new projects) the :djadmin:`runserver` command will be overridden
929 with its own :ref:`runserver<staticfiles-runserver>` command.
930
931 Logging of each request and response of the server is sent to the
932 :ref:`django-server-logger` logger.
933
934 .. django-admin-option:: --noreload
935
936 Disables the auto-reloader. This means any Python code changes you make while
937 the server is running will *not* take effect if the particular Python modules
938 have already been loaded into memory.
939
940 .. django-admin-option:: --nothreading
941
942 Disables use of threading in the development server. The server is
943 multithreaded by default.
944
945 .. django-admin-option:: --ipv6, -6
946
947 Uses IPv6 for the development server. This changes the default IP address from
948 ``127.0.0.1`` to ``::1``.
949
950 .. envvar:: DJANGO_RUNSERVER_HIDE_WARNING
951
952 .. versionadded:: 5.2
953
954 By default, a warning is printed to the console that ``runserver`` is not
955 suitable for production:
956
957 .. code-block:: text
958
959 WARNING: This is a development server. Do not use it in a production setting. Use a production WSGI or ASGI server instead.
960 For more information on production servers see: https://docs.djangoproject.com/en/|version|/howto/deployment/
961
962 Set this environment variable to ``"true"`` to hide this warning.
963
964 Examples of using different ports and addresses
965 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
966
967 Port 8000 on IP address ``127.0.0.1``:
968
969 .. console::
970
971 django-admin runserver
972
973 Port 8000 on IP address ``1.2.3.4``:
974
975 .. console::
976
977 django-admin runserver 1.2.3.4:8000
978
979 Port 7000 on IP address ``127.0.0.1``:
980
981 .. console::
982
983 django-admin runserver 7000
984
985 Port 7000 on IP address ``1.2.3.4``:
986
987 .. console::
988
989 django-admin runserver 1.2.3.4:7000
990
991 Port 8000 on IPv6 address ``::1``:
992
993 .. console::
994
995 django-admin runserver -6
996
997 Port 7000 on IPv6 address ``::1``:
998
999 .. console::
1000
1001 django-admin runserver -6 7000
1002
1003 Port 7000 on IPv6 address ``2001:0db8:1234:5678::9``:
1004
1005 .. console::
1006
1007 django-admin runserver [2001:0db8:1234:5678::9]:7000
1008
1009 Port 8000 on IPv4 address of host ``localhost``:
1010
1011 .. console::
1012
1013 django-admin runserver localhost:8000
1014
1015 Port 8000 on IPv6 address of host ``localhost``:
1016
1017 .. console::
1018
1019 django-admin runserver -6 localhost:8000
1020
1021 Serving static files with the development server
1022 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1023
1024 By default, the development server doesn't serve any static files for your site
1025 (such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If
1026 you want to configure Django to serve static media, read
1027 :doc:`/howto/static-files/index`.
1028
1029 Serving with ASGI in development
1030 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1031
1032 Django's ``runserver`` command provides a WSGI server. In order to run under
1033 ASGI you will need to use an :doc:`ASGI server </howto/deployment/asgi/index>`.
1034 The Django Daphne project provides :ref:`daphne-runserver` that you can use.
1035
1036 ``sendtestemail``
1037 -----------------
1038
1039 .. django-admin:: sendtestemail [email [email ...]]
1040
1041 Sends a test email (to confirm email sending through Django is working) to the
1042 recipient(s) specified. For example:
1043
1044 .. console::
1045
1046 django-admin sendtestemail [email protected] [email protected]
1047
1048 There are a couple of options, and you may use any combination of them
1049 together:
1050
1051 .. django-admin-option:: --managers
1052
1053 Mails the email addresses specified in :setting:`MANAGERS` using
1054 :func:`~django.core.mail.mail_managers`.
1055
1056 .. django-admin-option:: --admins
1057
1058 Mails the email addresses specified in :setting:`ADMINS` using
1059 :func:`~django.core.mail.mail_admins`.
1060
1061 ``shell``
1062 ---------
1063
1064 .. django-admin:: shell
1065
1066 Starts the Python interactive interpreter.
1067
1068 All models from installed apps are automatically imported into the shell
1069 environment. Models from apps listed earlier in :setting:`INSTALLED_APPS` take
1070 precedence. For a ``--verbosity`` of 2 or higher, the automatically imported
1071 objects will be listed. To disable automatic importing entirely, use the
1072 ``--no-imports`` flag.
1073
1074 See the guide on :ref:`customizing this behaviour
1075 <customizing-shell-auto-imports>` to add or remove automatic imports.
1076
1077 .. versionchanged:: 5.2
1078
1079 Automatic models import was added.
1080
1081 .. django-admin-option:: --interface {ipython,bpython,python}, -i {ipython,bpython,python}
1082
1083 Specifies the shell to use. By default, Django will use IPython_ or bpython_ if
1084 either is installed. If both are installed, specify which one you want like so:
1085
1086 IPython:
1087
1088 .. console::
1089
1090 django-admin shell -i ipython
1091
1092 bpython:
1093
1094 .. console::
1095
1096 django-admin shell -i bpython
1097
1098 If you have a "rich" shell installed but want to force use of the "plain"
1099 Python interpreter, use ``python`` as the interface name, like so:
1100
1101 .. console::
1102
1103 django-admin shell -i python
1104
1105 .. _IPython: https://ipython.org/
1106 .. _bpython: https://bpython-interpreter.org/
1107
1108 .. django-admin-option:: --no-startup
1109
1110 Disables reading the startup script for the "plain" Python interpreter. By
1111 default, the script pointed to by the :envvar:`PYTHONSTARTUP` environment
1112 variable or the ``~/.pythonrc.py`` script is read.
1113
1114 .. django-admin-option:: --no-imports
1115
1116 .. versionadded:: 5.2
1117
1118 Disables the automatic import of models from :setting:`INSTALLED_APPS`.
1119
1120 .. django-admin-option:: --command COMMAND, -c COMMAND
1121
1122 Lets you pass a command as a string to execute it as Django, like so:
1123
1124 .. console::
1125
1126 django-admin shell --command="import django; print(django.__version__)"
1127
1128 You can also pass code in on standard input to execute it. For example:
1129
1130 .. code-block:: console
1131
1132 $ django-admin shell <<EOF
1133 > import django
1134 > print(django.__version__)
1135 > EOF
1136
1137 On Windows, the REPL is output due to implementation limits of
1138 :func:`select.select` on that platform.
1139
1140 ``showmigrations``
1141 ------------------
1142
1143 .. django-admin:: showmigrations [app_label [app_label ...]]
1144
1145 Shows all migrations in a project. You can choose from one of two formats:
1146
1147 .. django-admin-option:: --list, -l
1148
1149 Lists all of the apps Django knows about, the migrations available for each
1150 app, and whether or not each migration is applied (marked by an ``[X]`` next to
1151 the migration name). For a ``--verbosity`` of 2 and above, the applied
1152 datetimes are also shown.
1153
1154 Apps without migrations are also listed, but have ``(no migrations)`` printed
1155 under them.
1156
1157 This is the default output format.
1158
1159 .. django-admin-option:: --plan, -p
1160
1161 Shows the migration plan Django will follow to apply migrations. Like
1162 ``--list``, applied migrations are marked by an ``[X]``. For a ``--verbosity``
1163 of 2 and above, all dependencies of a migration will also be shown.
1164
1165 ``app_label``\s arguments limit the output, however, dependencies of provided
1166 apps may also be included.
1167
1168 .. django-admin-option:: --database DATABASE
1169
1170 Specifies the database to examine. Defaults to ``default``.
1171
1172 ``sqlflush``
1173 ------------
1174
1175 .. django-admin:: sqlflush
1176
1177 Prints the SQL statements that would be executed for the :djadmin:`flush`
1178 command.
1179
1180 .. django-admin-option:: --database DATABASE
1181
1182 Specifies the database for which to print the SQL. Defaults to ``default``.
1183
1184 ``sqlmigrate``
1185 --------------
1186
1187 .. django-admin:: sqlmigrate app_label migration_name
1188
1189 Prints the SQL for the named migration. This requires an active database
1190 connection, which it will use to resolve constraint names; this means you must
1191 generate the SQL against a copy of the database you wish to later apply it on.
1192
1193 Note that ``sqlmigrate`` doesn't colorize its output.
1194
1195 .. django-admin-option:: --backwards
1196
1197 Generates the SQL for unapplying the migration. By default, the SQL created is
1198 for running the migration in the forwards direction.
1199
1200 .. django-admin-option:: --database DATABASE
1201
1202 Specifies the database for which to generate the SQL. Defaults to ``default``.
1203
1204 ``sqlsequencereset``
1205 --------------------
1206
1207 .. django-admin:: sqlsequencereset app_label [app_label ...]
1208
1209 Prints the SQL statements for resetting sequences for the given app name(s).
1210
1211 Sequences are indexes used by some database engines to track the next available
1212 number for automatically incremented fields.
1213
1214 Use this command to generate SQL which will fix cases where a sequence is out
1215 of sync with its automatically incremented field data.
1216
1217 .. django-admin-option:: --database DATABASE
1218
1219 Specifies the database for which to print the SQL. Defaults to ``default``.
1220
1221 ``squashmigrations``
1222 --------------------
1223
1224 .. django-admin:: squashmigrations app_label [start_migration_name] migration_name
1225
1226 Squashes the migrations for ``app_label`` up to and including ``migration_name``
1227 down into fewer migrations, if possible. The resulting squashed migrations
1228 can live alongside the unsquashed ones safely. For more information,
1229 please read :ref:`migration-squashing`.
1230
1231 When ``start_migration_name`` is given, Django will only include migrations
1232 starting from and including this migration. This helps to mitigate the
1233 squashing limitation of :class:`~django.db.migrations.operations.RunPython` and
1234 :class:`django.db.migrations.operations.RunSQL` migration operations.
1235
1236 .. django-admin-option:: --no-optimize
1237
1238 Disables the optimizer when generating a squashed migration. By default, Django
1239 will try to optimize the operations in your migrations to reduce the size of
1240 the resulting file. Use this option if this process is failing or creating
1241 incorrect migrations, though please also file a Django bug report about the
1242 behavior, as optimization is meant to be safe.
1243
1244 .. django-admin-option:: --noinput, --no-input
1245
1246 Suppresses all user prompts.
1247
1248 .. django-admin-option:: --squashed-name SQUASHED_NAME
1249
1250 Sets the name of the squashed migration. When omitted, the name is based on the
1251 first and last migration, with ``_squashed_`` in between.
1252
1253 .. django-admin-option:: --no-header
1254
1255 Generate squashed migration file without Django version and timestamp header.
1256
1257 ``startapp``
1258 ------------
1259
1260 .. django-admin:: startapp name [directory]
1261
1262 Creates a Django app directory structure for the given app name in the current
1263 directory or the given destination.
1264
1265 By default, :source:`the new directory <django/conf/app_template>` contains a
1266 ``models.py`` file and other app template files. If only the app name is given,
1267 the app directory will be created in the current working directory.
1268
1269 If the optional destination is provided, Django will use that existing
1270 directory rather than creating a new one. You can use '.' to denote the current
1271 working directory.
1272
1273 For example:
1274
1275 .. console::
1276
1277 django-admin startapp myapp /Users/jezdez/Code/myapp
1278
1279 .. _custom-app-and-project-templates:
1280
1281 .. django-admin-option:: --template TEMPLATE
1282
1283 Provides the path to a directory with a custom app template file, or a path to
1284 an uncompressed archive (``.tar``) or a compressed archive (``.tar.gz``,
1285 ``.tar.bz2``, ``.tar.xz``, ``.tar.lzma``, ``.tgz``, ``.tbz2``, ``.txz``,
1286 ``.tlz``, ``.zip``) containing the app template files.
1287
1288 For example, this would look for an app template in the given directory when
1289 creating the ``myapp`` app:
1290
1291 .. console::
1292
1293 django-admin startapp --template=/Users/jezdez/Code/my_app_template myapp
1294
1295 Django will also accept URLs (``http``, ``https``, ``ftp``) to compressed
1296 archives with the app template files, downloading and extracting them on the
1297 fly.
1298
1299 For example, taking advantage of GitHub's feature to expose repositories as
1300 zip files, you can use a URL like:
1301
1302 .. console::
1303
1304 django-admin startapp --template=https://github.com/githubuser/django-app-template/archive/main.zip myapp
1305
1306 .. warning::
1307
1308 Templates provided via ``--template`` are used as is. Malicious or poorly
1309 constructed templates may introduce security weaknesses or unintended
1310 behavior. Compressed archives may also consume excessive resources during
1311 extraction, potentially causing crashes or hangs.
1312
1313 Contents of templates should be carefully inspected before use.
1314
1315 .. django-admin-option:: --extension EXTENSIONS, -e EXTENSIONS
1316
1317 Specifies which file extensions in the app template should be rendered with the
1318 template engine. Defaults to ``py``.
1319
1320 .. django-admin-option:: --name FILES, -n FILES
1321
1322 Specifies which files in the app template (in addition to those matching
1323 ``--extension``) should be rendered with the template engine. Defaults to an
1324 empty list.
1325
1326 .. django-admin-option:: --exclude DIRECTORIES, -x DIRECTORIES
1327
1328 Specifies which directories in the app template should be excluded, in addition
1329 to ``.git`` and ``__pycache__``. If this option is not provided, directories
1330 named ``__pycache__`` or starting with ``.`` will be excluded.
1331
1332 The :class:`template context <django.template.Context>` used for all matching
1333 files is:
1334
1335 - Any option passed to the ``startapp`` command (among the command's supported
1336 options)
1337 - ``app_name`` -- the app name as passed to the command
1338 - ``app_directory`` -- the full path of the newly created app
1339 - ``camel_case_app_name`` -- the app name in camel case format
1340 - ``docs_version`` -- the version of the documentation: ``'dev'`` or ``'1.x'``
1341 - ``django_version`` -- the version of Django, e.g. ``'2.0.3'``
1342
1343 .. _render_warning:
1344
1345 .. warning::
1346
1347 When the app template files are rendered with the Django template
1348 engine (by default all ``*.py`` files), Django will also replace all
1349 stray template variables contained. For example, if one of the Python files
1350 contains a docstring explaining a particular feature related
1351 to template rendering, it might result in an incorrect example.
1352
1353 To work around this problem, you can use the :ttag:`templatetag`
1354 template tag to "escape" the various parts of the template syntax.
1355
1356 In addition, to allow Python template files that contain Django template
1357 language syntax while also preventing packaging systems from trying to
1358 byte-compile invalid ``*.py`` files, template files ending with ``.py-tpl``
1359 will be renamed to ``.py``.
1360
1361 .. _trusted_code_warning:
1362
1363 .. warning::
1364
1365 The contents of custom app (or project) templates should always be
1366 audited before use: Such templates define code that will become
1367 part of your project, and this means that such code will be trusted
1368 as much as any app you install, or code you write yourself.
1369 Further, even rendering the templates is, effectively, executing
1370 code that was provided as input to the management command. The
1371 Django template language may provide wide access into the system,
1372 so make sure any custom template you use is worthy of your trust.
1373
1374 ``startproject``
1375 ----------------
1376
1377 .. django-admin:: startproject name [directory]
1378
1379 Creates a Django project directory structure for the given project name in
1380 the current directory or the given destination.
1381
1382 By default, :source:`the new directory <django/conf/project_template>` contains
1383 ``manage.py`` and a project package (containing a ``settings.py`` and other
1384 files).
1385
1386 If only the project name is given, both the project directory and project
1387 package will be named ``<projectname>`` and the project directory
1388 will be created in the current working directory.
1389
1390 If the optional destination is provided, Django will use that existing
1391 directory as the project directory, and create ``manage.py`` and the project
1392 package within it. Use '.' to denote the current working directory.
1393
1394 For example:
1395
1396 .. console::
1397
1398 django-admin startproject myproject /Users/jezdez/Code/myproject_repo
1399
1400 .. django-admin-option:: --template TEMPLATE
1401
1402 Specifies a directory, file path, or URL of a custom project template. See the
1403 :option:`startapp --template` documentation for examples and usage. The same
1404 **security considerations** described for ``startapp`` templates apply here:
1405 malicious or poorly constructed templates may introduce weaknesses or consume
1406 excessive resources, and templates should be carefully inspected before use.
1407
1408 .. django-admin-option:: --extension EXTENSIONS, -e EXTENSIONS
1409
1410 Specifies which file extensions in the project template should be rendered with
1411 the template engine. Defaults to ``py``.
1412
1413 .. django-admin-option:: --name FILES, -n FILES
1414
1415 Specifies which files in the project template (in addition to those matching
1416 ``--extension``) should be rendered with the template engine. Defaults to an
1417 empty list.
1418
1419 .. django-admin-option:: --exclude DIRECTORIES, -x DIRECTORIES
1420
1421 Specifies which directories in the project template should be excluded, in
1422 addition to ``.git`` and ``__pycache__``. If this option is not provided,
1423 directories named ``__pycache__`` or starting with ``.`` will be excluded.
1424
1425 The :class:`template context <django.template.Context>` used is:
1426
1427 - Any option passed to the ``startproject`` command (among the command's
1428 supported options)
1429 - ``project_name`` -- the project name as passed to the command
1430 - ``project_directory`` -- the full path of the newly created project
1431 - ``secret_key`` -- a random key for the :setting:`SECRET_KEY` setting
1432 - ``docs_version`` -- the version of the documentation: ``'dev'`` or ``'1.x'``
1433 - ``django_version`` -- the version of Django, e.g. ``'2.0.3'``
1434
1435 Please also see the :ref:`rendering warning <render_warning>` and
1436 :ref:`trusted code warning <trusted_code_warning>` as mentioned for
1437 :djadmin:`startapp`.
1438
1439 ``test``
1440 --------
1441
1442 .. django-admin:: test [test_label [test_label ...]]
1443
1444 Runs tests for all installed apps. See :doc:`/topics/testing/index` for more
1445 information.
1446
1447 .. django-admin-option:: --failfast
1448
1449 Stops running tests and reports the failure immediately after a test fails.
1450
1451 .. django-admin-option:: --testrunner TESTRUNNER
1452
1453 Controls the test runner class that is used to execute tests. This value
1454 overrides the value provided by the :setting:`TEST_RUNNER` setting.
1455
1456 .. django-admin-option:: --noinput, --no-input
1457
1458 Suppresses all user prompts. A typical prompt is a warning about deleting an
1459 existing test database.
1460
1461 Test runner options
1462 ~~~~~~~~~~~~~~~~~~~
1463
1464 The ``test`` command receives options on behalf of the specified
1465 :option:`--testrunner`. These are the options of the default test runner:
1466 :class:`~django.test.runner.DiscoverRunner`.
1467
1468 .. django-admin-option:: --keepdb
1469
1470 Preserves the test database between test runs. This has the advantage of
1471 skipping both the create and destroy actions which can greatly decrease the
1472 time to run tests, especially those in a large test suite. If the test database
1473 does not exist, it will be created on the first run and then preserved for each
1474 subsequent run. Unless the :setting:`MIGRATE <TEST_MIGRATE>` test setting is
1475 ``False``, any unapplied migrations will also be applied to the test database
1476 before running the test suite.
1477
1478 .. django-admin-option:: --shuffle [SEED]
1479
1480 Randomizes the order of tests before running them. This can help detect tests
1481 that aren't properly isolated. The test order generated by this option is a
1482 deterministic function of the integer seed given. When no seed is passed, a
1483 seed is chosen randomly and printed to the console. To repeat a particular test
1484 order, pass a seed. The test orders generated by this option preserve Django's
1485 :ref:`guarantees on test order <order-of-tests>`. They also keep tests grouped
1486 by test case class.
1487
1488 The shuffled orderings also have a special consistency property useful when
1489 narrowing down isolation issues. Namely, for a given seed and when running a
1490 subset of tests, the new order will be the original shuffling restricted to the
1491 smaller set. Similarly, when adding tests while keeping the seed the same, the
1492 order of the original tests will be the same in the new order.
1493
1494 .. django-admin-option:: --reverse, -r
1495
1496 Sorts test cases in the opposite execution order. This may help in debugging
1497 the side effects of tests that aren't properly isolated. :ref:`Grouping by test
1498 class <order-of-tests>` is preserved when using this option. This can be used
1499 in conjunction with ``--shuffle`` to reverse the order for a particular seed.
1500
1501 .. django-admin-option:: --debug-mode
1502
1503 Sets the :setting:`DEBUG` setting to ``True`` prior to running tests. This may
1504 help troubleshoot test failures.
1505
1506 .. django-admin-option:: --debug-sql, -d
1507
1508 Enables :ref:`SQL logging <django-db-logger>` for failing tests. If
1509 ``--verbosity`` is ``2``, then queries in passing tests are also output.
1510
1511 .. django-admin-option:: --parallel [N]
1512
1513 .. envvar:: DJANGO_TEST_PROCESSES
1514
1515 Runs tests in separate parallel processes. Since modern processors have
1516 multiple cores, this allows running tests significantly faster.
1517
1518 Using ``--parallel`` without a value, or with the value ``auto``, runs one test
1519 process per core according to :func:`multiprocessing.cpu_count()`. You can
1520 override this by passing the desired number of processes, e.g.
1521 ``--parallel 4``, or by setting the :envvar:`DJANGO_TEST_PROCESSES` environment
1522 variable.
1523
1524 Django distributes test cases — :class:`unittest.TestCase` subclasses — to
1525 subprocesses. If there are fewer test case classes than configured processes,
1526 Django will reduce the number of processes accordingly.
1527
1528 Each process gets its own database. You must ensure that different test case
1529 classes don't access the same resources. For instance, test case classes that
1530 touch the filesystem should create a temporary directory for their own use.
1531
1532 .. note::
1533
1534 If you have test classes that cannot be run in parallel, you can use
1535 ``SerializeMixin`` to run them sequentially. See :ref:`Enforce running test
1536 classes sequentially <topics-testing-enforce-run-sequentially>`.
1537
1538 This option requires the third-party ``tblib`` package to display tracebacks
1539 correctly:
1540
1541 .. code-block:: console
1542
1543 $ python -m pip install tblib
1544
1545 This feature isn't available on Windows. It doesn't work with the Oracle
1546 database backend either.
1547
1548 If you want to use :mod:`pdb` while debugging tests, you must disable parallel
1549 execution (``--parallel=1``). You'll see something like ``bdb.BdbQuit`` if you
1550 don't.
1551
1552 .. warning::
1553
1554 When test parallelization is enabled and a test fails, Django may be
1555 unable to display the exception traceback. This can make debugging
1556 difficult. If you encounter this problem, run the affected test without
1557 parallelization to see the traceback of the failure.
1558
1559 This is a known limitation. It arises from the need to serialize objects
1560 in order to exchange them between processes. See
1561 :ref:`python:pickle-picklable` for details.
1562
1563 .. option:: --tag TAGS
1564
1565 Runs only tests :ref:`marked with the specified tags <topics-tagging-tests>`.
1566 May be specified multiple times and combined with :option:`test --exclude-tag`.
1567
1568 Tests that fail to load are always considered matching.
1569
1570 .. option:: --exclude-tag EXCLUDE_TAGS
1571
1572 Excludes tests :ref:`marked with the specified tags <topics-tagging-tests>`.
1573 May be specified multiple times and combined with :option:`test --tag`.
1574
1575 .. django-admin-option:: -k TEST_NAME_PATTERNS
1576
1577 Runs test methods and classes matching test name patterns, in the same way as
1578 :option:`unittest's -k option<unittest.-k>`. Can be specified multiple times.
1579
1580 .. django-admin-option:: --pdb
1581
1582 Spawns a ``pdb`` debugger at each test error or failure. If you have it
1583 installed, ``ipdb`` is used instead.
1584
1585 .. django-admin-option:: --buffer, -b
1586
1587 Discards output (``stdout`` and ``stderr``) for passing tests, in the same way
1588 as :option:`unittest's --buffer option<unittest.-b>`.
1589
1590 .. django-admin-option:: --no-faulthandler
1591
1592 Django automatically calls :func:`faulthandler.enable()` when starting the
1593 tests, which allows it to print a traceback if the interpreter crashes. Pass
1594 ``--no-faulthandler`` to disable this behavior.
1595
1596 .. django-admin-option:: --timing
1597
1598 Outputs timings, including database setup and total run time.
1599
1600 .. django-admin-option:: --durations N
1601
1602 Shows the N slowest test cases (N=0 for all).
1603
1604 .. admonition:: Python 3.12 and later
1605
1606 This feature is only available for Python 3.12 and later.
1607
1608 ``testserver``
1609 --------------
1610
1611 .. django-admin:: testserver [fixture [fixture ...]]
1612
1613 Runs a Django development server (as in :djadmin:`runserver`) using data from
1614 the given fixture(s).
1615
1616 For example, this command:
1617
1618 .. console::
1619
1620 django-admin testserver mydata.json
1621
1622 ...would perform the following steps:
1623
1624 #. Create a test database, as described in :ref:`the-test-database`.
1625 #. Populate the test database with fixture data from the given fixtures.
1626 (For more on fixtures, see the documentation for :djadmin:`loaddata` above.)
1627 #. Runs the Django development server (as in :djadmin:`runserver`), pointed at
1628 this newly created test database instead of your production database.
1629
1630 This is useful in a number of ways:
1631
1632 * When you're writing :doc:`unit tests </topics/testing/overview>` of how your views
1633 act with certain fixture data, you can use ``testserver`` to interact with
1634 the views in a web browser, manually.
1635
1636 * Let's say you're developing your Django application and have a "pristine"
1637 copy of a database that you'd like to interact with. You can dump your
1638 database to a :ref:`fixture <fixtures-explanation>` (using the
1639 :djadmin:`dumpdata` command, explained above), then use ``testserver`` to run
1640 your web application with that data. With this arrangement, you have the
1641 flexibility of messing up your data in any way, knowing that whatever data
1642 changes you're making are only being made to a test database.
1643
1644 Note that this server does *not* automatically detect changes to your Python
1645 source code (as :djadmin:`runserver` does). It does, however, detect changes to
1646 templates.
1647
1648 .. django-admin-option:: --addrport ADDRPORT
1649
1650 Specifies a different port, or IP address and port, from the default of
1651 ``127.0.0.1:8000``. This value follows exactly the same format and serves
1652 exactly the same function as the argument to the :djadmin:`runserver` command.
1653
1654 Examples:
1655
1656 To run the test server on port 7000 with ``fixture1`` and ``fixture2``:
1657
1658 .. console::
1659
1660 django-admin testserver --addrport 7000 fixture1 fixture2
1661 django-admin testserver fixture1 fixture2 --addrport 7000
1662
1663 (The above statements are equivalent. We include both of them to demonstrate
1664 that it doesn't matter whether the options come before or after the fixture
1665 arguments.)
1666
1667 To run on 1.2.3.4:7000 with a ``test`` fixture:
1668
1669 .. console::
1670
1671 django-admin testserver --addrport 1.2.3.4:7000 test
1672
1673 .. django-admin-option:: --noinput, --no-input
1674
1675 Suppresses all user prompts. A typical prompt is a warning about deleting an
1676 existing test database.
1677
1678 Commands provided by applications
1679 =================================
1680
1681 Some commands are only available when the ``django.contrib`` application that
1682 :doc:`implements </howto/custom-management-commands>` them has been
1683 :setting:`enabled <INSTALLED_APPS>`. This section describes them grouped by
1684 their application.
1685
1686 ``django.contrib.auth``
1687 -----------------------
1688
1689 ``changepassword``
1690 ~~~~~~~~~~~~~~~~~~
1691
1692 .. django-admin:: changepassword [<username>]
1693
1694 This command is only available if Django's :doc:`authentication system
1695 </topics/auth/index>` (``django.contrib.auth``) is installed.
1696
1697 Allows changing a user's password. It prompts you to enter a new password twice
1698 for the given user. If the entries are identical, this immediately becomes the
1699 new password. If you do not supply a user, the command will attempt to change
1700 the password whose username matches the current user.
1701
1702 .. django-admin-option:: --database DATABASE
1703
1704 Specifies the database to query for the user. Defaults to ``default``.
1705
1706 Example usage:
1707
1708 .. console::
1709
1710 django-admin changepassword ringo
1711
1712 ``createsuperuser``
1713 ~~~~~~~~~~~~~~~~~~~
1714
1715 .. django-admin:: createsuperuser
1716
1717 .. envvar:: DJANGO_SUPERUSER_PASSWORD
1718
1719 This command is only available if Django's :doc:`authentication system
1720 </topics/auth/index>` (``django.contrib.auth``) is installed.
1721
1722 Creates a superuser account (a user who has all permissions). This is
1723 useful if you need to create an initial superuser account or if you need to
1724 programmatically generate superuser accounts for your site(s).
1725
1726 When run interactively, this command will prompt for a password for
1727 the new superuser account. When run non-interactively, you can provide
1728 a password by setting the :envvar:`DJANGO_SUPERUSER_PASSWORD` environment
1729 variable. Otherwise, no password will be set, and the superuser account will
1730 not be able to log in until a password has been manually set for it.
1731
1732 In non-interactive mode, the
1733 :attr:`~django.contrib.auth.models.CustomUser.USERNAME_FIELD` and required
1734 fields (listed in
1735 :attr:`~django.contrib.auth.models.CustomUser.REQUIRED_FIELDS`) fall back to
1736 ``DJANGO_SUPERUSER_<uppercase_field_name>`` environment variables, unless they
1737 are overridden by a command line argument. For example, to provide an ``email``
1738 field, you can use ``DJANGO_SUPERUSER_EMAIL`` environment variable.
1739
1740 .. django-admin-option:: --noinput, --no-input
1741
1742 Suppresses all user prompts. If a suppressed prompt cannot be resolved
1743 automatically, the command will exit with error code 1.
1744
1745 .. django-admin-option:: --username USERNAME
1746 .. django-admin-option:: --email EMAIL
1747
1748 The username and email address for the new account can be supplied by
1749 using the ``--username`` and ``--email`` arguments on the command
1750 line. If either of those is not supplied, ``createsuperuser`` will prompt for
1751 it when running interactively.
1752
1753 .. django-admin-option:: --database DATABASE
1754
1755 Specifies the database into which the superuser object will be saved.
1756
1757 You can subclass the management command and override ``get_input_data()`` if you
1758 want to customize data input and validation. Consult the source code for
1759 details on the existing implementation and the method's parameters. For example,
1760 it could be useful if you have a ``ForeignKey`` in
1761 :attr:`~django.contrib.auth.models.CustomUser.REQUIRED_FIELDS` and want to
1762 allow creating an instance instead of entering the primary key of an existing
1763 instance.
1764
1765 ``django.contrib.contenttypes``
1766 -------------------------------
1767
1768 ``remove_stale_contenttypes``
1769 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1770
1771 .. django-admin:: remove_stale_contenttypes
1772
1773 This command is only available if Django's :doc:`contenttypes app
1774 </ref/contrib/contenttypes>` (:mod:`django.contrib.contenttypes`) is installed.
1775
1776 Deletes stale content types (from deleted models) in your database. Any objects
1777 that depend on the deleted content types will also be deleted. A list of
1778 deleted objects will be displayed before you confirm it's okay to proceed with
1779 the deletion.
1780
1781 .. django-admin-option:: --database DATABASE
1782
1783 Specifies the database to use. Defaults to ``default``.
1784
1785 .. django-admin-option:: --include-stale-apps
1786
1787 Deletes stale content types including ones from previously installed apps that
1788 have been removed from :setting:`INSTALLED_APPS`. Defaults to ``False``.
1789
1790 ``django.contrib.gis``
1791 ----------------------
1792
1793 ``ogrinspect``
1794 ~~~~~~~~~~~~~~
1795
1796 This command is only available if :doc:`GeoDjango </ref/contrib/gis/index>`
1797 (``django.contrib.gis``) is installed.
1798
1799 Please refer to its :djadmin:`description <ogrinspect>` in the GeoDjango
1800 documentation.
1801
1802 ``django.contrib.sessions``
1803 ---------------------------
1804
1805 ``clearsessions``
1806 ~~~~~~~~~~~~~~~~~
1807
1808 .. django-admin:: clearsessions
1809
1810 Can be run as a cron job or directly to clean out expired sessions.
1811
1812 ``django.contrib.staticfiles``
1813 ------------------------------
1814
1815 ``collectstatic``
1816 ~~~~~~~~~~~~~~~~~
1817
1818 This command is only available if the :doc:`static files application
1819 </howto/static-files/index>` (``django.contrib.staticfiles``) is installed.
1820
1821 Please refer to its :djadmin:`description <collectstatic>` in the
1822 :doc:`staticfiles </ref/contrib/staticfiles>` documentation.
1823
1824 ``findstatic``
1825 ~~~~~~~~~~~~~~
1826
1827 This command is only available if the :doc:`static files application
1828 </howto/static-files/index>` (``django.contrib.staticfiles``) is installed.
1829
1830 Please refer to its :djadmin:`description <findstatic>` in the :doc:`staticfiles
1831 </ref/contrib/staticfiles>` documentation.
1832
1833 Default options
1834 ===============
1835
1836 .. program:: None
1837
1838 Although some commands may allow their own custom options, every command
1839 allows for the following options by default:
1840
1841 .. django-admin-option:: --pythonpath PYTHONPATH
1842
1843 Adds the given filesystem path to the Python :py:data:`sys.path` module
1844 attribute. If this isn't provided, ``django-admin`` will use the
1845 :envvar:`PYTHONPATH` environment variable.
1846
1847 This option is unnecessary in ``manage.py``, because it takes care of setting
1848 the Python path for you.
1849
1850 Example usage:
1851
1852 .. console::
1853
1854 django-admin migrate --pythonpath='/home/djangoprojects/myproject'
1855
1856 .. django-admin-option:: --settings SETTINGS
1857
1858 Specifies the settings module to use. The settings module should be in Python
1859 package syntax, e.g. ``mysite.settings``. If this isn't provided,
1860 ``django-admin`` will use the :envvar:`DJANGO_SETTINGS_MODULE` environment
1861 variable.
1862
1863 This option is unnecessary in ``manage.py``, because it uses
1864 ``settings.py`` from the current project by default.
1865
1866 Example usage:
1867
1868 .. console::
1869
1870 django-admin migrate --settings=mysite.settings
1871
1872 .. django-admin-option:: --traceback
1873
1874 Displays a full stack trace when a :exc:`~django.core.management.CommandError`
1875 is raised. By default, ``django-admin`` will show an error message when a
1876 ``CommandError`` occurs and a full stack trace for any other exception.
1877
1878 This option is ignored by :djadmin:`runserver`.
1879
1880 Example usage:
1881
1882 .. console::
1883
1884 django-admin migrate --traceback
1885
1886 .. django-admin-option:: --verbosity {0,1,2,3}, -v {0,1,2,3}
1887
1888 Specifies the amount of notification and debug information that a command
1889 should print to the console.
1890
1891 * ``0`` means no output.
1892 * ``1`` means normal output (default).
1893 * ``2`` means verbose output.
1894 * ``3`` means *very* verbose output.
1895
1896 This option is ignored by :djadmin:`runserver`.
1897
1898 Example usage:
1899
1900 .. console::
1901
1902 django-admin migrate --verbosity 2
1903
1904 .. django-admin-option:: --no-color
1905
1906 Disables colorized command output. Some commands format their output to be
1907 colorized. For example, errors will be printed to the console in red and SQL
1908 statements will be syntax highlighted.
1909
1910 Example usage:
1911
1912 .. console::
1913
1914 django-admin runserver --no-color
1915
1916 .. django-admin-option:: --force-color
1917
1918 Forces colorization of the command output if it would otherwise be disabled
1919 as discussed in :ref:`syntax-coloring`. For example, you may want to pipe
1920 colored output to another command.
1921
1922 .. django-admin-option:: --skip-checks
1923
1924 Skips running system checks prior to running the command. This option is only
1925 available if the
1926 :attr:`~django.core.management.BaseCommand.requires_system_checks` command
1927 attribute is not an empty list or tuple.
1928
1929 Example usage:
1930
1931 .. console::
1932
1933 django-admin migrate --skip-checks
1934
1935 Extra niceties
1936 ==============
1937
1938 .. _syntax-coloring:
1939
1940 Syntax coloring
1941 ---------------
1942
1943 .. envvar:: DJANGO_COLORS
1944
1945 The ``django-admin`` / ``manage.py`` commands will use pretty
1946 color-coded output if your terminal supports ANSI-colored output. It
1947 won't use the color codes if you're piping the command's output to
1948 another program unless the :option:`--force-color` option is used.
1949
1950 Windows support
1951 ~~~~~~~~~~~~~~~
1952
1953 On Windows 10, the `Windows Terminal`_ application, `VS Code`_, and PowerShell
1954 (where virtual terminal processing is enabled) allow colored output, and are
1955 supported by default.
1956
1957 Under Windows, the legacy ``cmd.exe`` native console doesn't support ANSI
1958 escape sequences so by default there is no color output. In this case either of
1959 two third-party libraries are needed:
1960
1961 * Install :pypi:`colorama`, a Python package that translates ANSI color codes
1962 into Windows API calls. Django commands will detect its presence and will
1963 make use of its services to color output just like on Unix-based platforms.
1964 ``colorama`` can be installed via pip:
1965
1966 .. code-block:: doscon
1967
1968 ...\> py -m pip install "colorama >= 0.4.6"
1969
1970 * Install `ANSICON`_, a third-party tool that allows ``cmd.exe`` to process
1971 ANSI color codes. Django commands will detect its presence and will make use
1972 of its services to color output just like on Unix-based platforms.
1973
1974 Other modern terminal environments on Windows, that support terminal colors,
1975 but which are not automatically detected as supported by Django, may "fake" the
1976 installation of ``ANSICON`` by setting the appropriate environmental variable,
1977 ``ANSICON="on"``.
1978
1979 .. _`Windows Terminal`: https://www.microsoft.com/en-us/p/windows-terminal-preview/9n0dx20hk701
1980 .. _`VS Code`: https://code.visualstudio.com
1981 .. _ANSICON: http://adoxa.altervista.org/ansicon/
1982
1983 Custom colors
1984 ~~~~~~~~~~~~~
1985
1986 The colors used for syntax highlighting can be customized. Django
1987 ships with three color palettes:
1988
1989 * ``dark``, suited to terminals that show white text on a black
1990 background. This is the default palette.
1991
1992 * ``light``, suited to terminals that show black text on a white
1993 background.
1994
1995 * ``nocolor``, which disables syntax highlighting.
1996
1997 You select a palette by setting a :envvar:`DJANGO_COLORS` environment
1998 variable to specify the palette you want to use. For example, to
1999 specify the ``light`` palette under a Unix or OS/X BASH shell, you
2000 would run the following at a command prompt:
2001
2002 .. code-block:: shell
2003
2004 export DJANGO_COLORS="light"
2005
2006 You can also customize the colors that are used. Django specifies a
2007 number of roles in which color is used:
2008
2009 * ``error`` - A major error.
2010 * ``notice`` - A minor error.
2011 * ``success`` - A success.
2012 * ``warning`` - A warning.
2013 * ``sql_field`` - The name of a model field in SQL.
2014 * ``sql_coltype`` - The type of a model field in SQL.
2015 * ``sql_keyword`` - An SQL keyword.
2016 * ``sql_table`` - The name of a model in SQL.
2017 * ``http_info`` - A 1XX HTTP Informational server response.
2018 * ``http_success`` - A 2XX HTTP Success server response.
2019 * ``http_not_modified`` - A 304 HTTP Not Modified server response.
2020 * ``http_redirect`` - A 3XX HTTP Redirect server response other than 304.
2021 * ``http_not_found`` - A 404 HTTP Not Found server response.
2022 * ``http_bad_request`` - A 4XX HTTP Bad Request server response other than 404.
2023 * ``http_server_error`` - A 5XX HTTP Server Error response.
2024 * ``migrate_heading`` - A heading in a migrations management command.
2025 * ``migrate_label`` - A migration name.
2026
2027 Each of these roles can be assigned a specific foreground and
2028 background color, from the following list:
2029
2030 * ``black``
2031 * ``red``
2032 * ``green``
2033 * ``yellow``
2034 * ``blue``
2035 * ``magenta``
2036 * ``cyan``
2037 * ``white``
2038
2039 Each of these colors can then be modified by using the following
2040 display options:
2041
2042 * ``bold``
2043 * ``underscore``
2044 * ``blink``
2045 * ``reverse``
2046 * ``conceal``
2047
2048 A color specification follows one of the following patterns:
2049
2050 * ``role=fg``
2051 * ``role=fg/bg``
2052 * ``role=fg,option,option``
2053 * ``role=fg/bg,option,option``
2054
2055 where ``role`` is the name of a valid color role, ``fg`` is the
2056 foreground color, ``bg`` is the background color and each ``option``
2057 is one of the color modifying options. Multiple color specifications
2058 are then separated by a semicolon. For example:
2059
2060 .. code-block:: shell
2061
2062 export DJANGO_COLORS="error=yellow/blue,blink;notice=magenta"
2063
2064 would specify that errors be displayed using blinking yellow on blue,
2065 and notices displayed using magenta. All other color roles would be
2066 left uncolored.
2067
2068 Colors can also be specified by extending a base palette. If you put
2069 a palette name in a color specification, all the colors implied by that
2070 palette will be loaded. So:
2071
2072 .. code-block:: shell
2073
2074 export DJANGO_COLORS="light;error=yellow/blue,blink;notice=magenta"
2075
2076 would specify the use of all the colors in the light color palette,
2077 *except* for the colors for errors and notices which would be
2078 overridden as specified.
2079
2080 Bash completion
2081 ---------------
2082
2083 If you use the Bash shell, consider installing the Django bash completion
2084 script, which lives in :source:`extras/django_bash_completion` in the Django source
2085 distribution. It enables tab-completion of ``django-admin`` and
2086 ``manage.py`` commands, so you can, for instance...
2087
2088 * Type ``django-admin``.
2089 * Press [TAB] to see all available options.
2090 * Type ``sql``, then [TAB], to see all available options whose names start
2091 with ``sql``.
2092
2093 See :doc:`/howto/custom-management-commands` for how to add customized actions.
2094
2095 Black formatting
2096 ----------------
2097
2098 The Python files created by :djadmin:`startproject`, :djadmin:`startapp`,
2099 :djadmin:`optimizemigration`, :djadmin:`makemigrations`, and
2100 :djadmin:`squashmigrations` are formatted using the ``black`` command if it is
2101 present on your ``PATH``.
2102
2103 If you have ``black`` globally installed, but do not wish it used for the
2104 current project, you can set the ``PATH`` explicitly:
2105
2106 .. code-block:: shell
2107
2108 PATH=path/to/venv/bin django-admin makemigrations
2109
2110 For commands using ``stdout`` you can pipe the output to ``black`` if needed:
2111
2112 .. code-block:: shell
2113
2114 django-admin inspectdb | black -
2115
2116 ==========================================
2117 Running management commands from your code
2118 ==========================================
2119
2120 .. function:: django.core.management.call_command(name, *args, **options)
2121
2122 To call a management command from code use ``call_command()``.
2123
2124 ``name``
2125 the name of the command to call or a command object. Passing the name is
2126 preferred unless the object is required for testing.
2127
2128 ``*args``
2129 a list of arguments accepted by the command. Arguments are passed to the
2130 argument parser, so you can use the same style as you would on the command
2131 line. For example, ``call_command('flush', '--verbosity=0')``.
2132
2133 ``**options``
2134 named options accepted on the command-line. Options are passed to the command
2135 without triggering the argument parser, which means you'll need to pass the
2136 correct type. For example, ``call_command('flush', verbosity=0)`` (zero must
2137 be an integer rather than a string).
2138
2139 Examples::
2140
2141 from django.core import management
2142 from django.core.management.commands import loaddata
2143
2144 management.call_command("flush", verbosity=0, interactive=False)
2145 management.call_command("loaddata", "test_data", verbosity=0)
2146 management.call_command(loaddata.Command(), "test_data", verbosity=0)
2147
2148 Note that command options that take no arguments are passed as keywords
2149 with ``True`` or ``False``, as you can see with the ``interactive`` option above.
2150
2151 Named arguments can be passed by using either one of the following syntaxes::
2152
2153 # Similar to the command line
2154 management.call_command("dumpdata", "--natural-foreign")
2155
2156 # Named argument similar to the command line minus the initial dashes and
2157 # with internal dashes replaced by underscores
2158 management.call_command("dumpdata", natural_foreign=True)
2159
2160 # `use_natural_foreign_keys` is the option destination variable
2161 management.call_command("dumpdata", use_natural_foreign_keys=True)
2162
2163 Some command options have different names when using ``call_command()`` instead
2164 of ``django-admin`` or ``manage.py``. For example, ``django-admin
2165 createsuperuser --no-input`` translates to ``call_command('createsuperuser',
2166 interactive=False)``. To find what keyword argument name to use for
2167 ``call_command()``, check the command's source code for the ``dest`` argument
2168 passed to ``parser.add_argument()``.
2169
2170 Command options which take multiple options are passed a list::
2171
2172 management.call_command("dumpdata", exclude=["contenttypes", "auth"])
2173
2174 The return value of the ``call_command()`` function is the same as the return
2175 value of the ``handle()`` method of the command.
2176
2177 Output redirection
2178 ==================
2179
2180 Note that you can redirect standard output and error streams as all commands
2181 support the ``stdout`` and ``stderr`` options. For example, you could write::
2182
2183 with open("/path/to/command_output", "w") as f:
2184 management.call_command("dumpdata", stdout=f)