mirror of https://github.com/django/django.git
2045 lines
70 KiB
Plaintext
2045 lines
70 KiB
Plaintext
==================================
|
||
``django-admin`` and ``manage.py``
|
||
==================================
|
||
|
||
``django-admin`` is Django's command-line utility for administrative tasks.
|
||
This document outlines all it can do.
|
||
|
||
In addition, ``manage.py`` is automatically created in each Django project. It
|
||
does the same thing as ``django-admin`` but also sets the
|
||
:envvar:`DJANGO_SETTINGS_MODULE` environment variable so that it points to your
|
||
project's ``settings.py`` file.
|
||
|
||
The ``django-admin`` script should be on your system path if you installed
|
||
Django via ``pip``. If it's not in your path, ensure you have your virtual
|
||
environment activated.
|
||
|
||
Generally, when working on a single Django project, it's easier to use
|
||
``manage.py`` than ``django-admin``. If you need to switch between multiple
|
||
Django settings files, use ``django-admin`` with
|
||
:envvar:`DJANGO_SETTINGS_MODULE` or the :option:`--settings` command line
|
||
option.
|
||
|
||
The command-line examples throughout this document use ``django-admin`` to
|
||
be consistent, but any example can use ``manage.py`` or ``python -m django``
|
||
just as well.
|
||
|
||
Usage
|
||
=====
|
||
|
||
.. console::
|
||
|
||
$ django-admin <command> [options]
|
||
$ manage.py <command> [options]
|
||
$ python -m django <command> [options]
|
||
|
||
``command`` should be one of the commands listed in this document.
|
||
``options``, which is optional, should be zero or more of the options available
|
||
for the given command.
|
||
|
||
Getting runtime help
|
||
--------------------
|
||
|
||
.. django-admin:: help
|
||
|
||
Run ``django-admin help`` to display usage information and a list of the
|
||
commands provided by each application.
|
||
|
||
Run ``django-admin help --commands`` to display a list of all available
|
||
commands.
|
||
|
||
Run ``django-admin help <command>`` to display a description of the given
|
||
command and a list of its available options.
|
||
|
||
App names
|
||
---------
|
||
|
||
Many commands take a list of "app names." An "app name" is the basename of
|
||
the package containing your models. For example, if your :setting:`INSTALLED_APPS`
|
||
contains the string ``'mysite.blog'``, the app name is ``blog``.
|
||
|
||
Determining the version
|
||
-----------------------
|
||
|
||
.. django-admin:: version
|
||
|
||
Run ``django-admin version`` to display the current Django version.
|
||
|
||
The output follows the schema described in :pep:`440`::
|
||
|
||
1.4.dev17026
|
||
1.4a1
|
||
1.4
|
||
|
||
Displaying debug output
|
||
-----------------------
|
||
|
||
.. program:: None
|
||
|
||
Use :option:`--verbosity` to specify the amount of notification and debug
|
||
information that ``django-admin`` prints to the console.
|
||
|
||
Available commands
|
||
==================
|
||
|
||
``check``
|
||
---------
|
||
|
||
.. django-admin:: check [app_label [app_label ...]]
|
||
|
||
Uses the :doc:`system check framework </ref/checks>` to inspect the entire
|
||
Django project for common problems.
|
||
|
||
By default, all apps will be checked. You can check a subset of apps by
|
||
providing a list of app labels as arguments::
|
||
|
||
django-admin check auth admin myapp
|
||
|
||
If you do not specify any app, all apps will be checked.
|
||
|
||
.. django-admin-option:: --tag TAGS, -t TAGS
|
||
|
||
The system check framework performs many different types of checks that are
|
||
:ref:`categorized with tags <system-check-builtin-tags>`. You can use these
|
||
tags to restrict the checks performed to just those in a particular category.
|
||
For example, to perform only models and compatibility checks, run::
|
||
|
||
django-admin check --tag models --tag compatibility
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
.. versionadded:: 3.1
|
||
|
||
Specifies the database to run checks requiring database access::
|
||
|
||
django-admin check --database default --database other
|
||
|
||
By default, these checks will not be run.
|
||
|
||
.. django-admin-option:: --list-tags
|
||
|
||
Lists all available tags.
|
||
|
||
.. django-admin-option:: --deploy
|
||
|
||
Activates some additional checks that are only relevant in a deployment setting.
|
||
|
||
You can use this option in your local development environment, but since your
|
||
local development settings module may not have many of your production settings,
|
||
you will probably want to point the ``check`` command at a different settings
|
||
module, either by setting the :envvar:`DJANGO_SETTINGS_MODULE` environment
|
||
variable, or by passing the ``--settings`` option::
|
||
|
||
django-admin check --deploy --settings=production_settings
|
||
|
||
Or you could run it directly on a production or staging deployment to verify
|
||
that the correct settings are in use (omitting ``--settings``). You could even
|
||
make it part of your integration test suite.
|
||
|
||
.. django-admin-option:: --fail-level {CRITICAL,ERROR,WARNING,INFO,DEBUG}
|
||
|
||
Specifies the message level that will cause the command to exit with a non-zero
|
||
status. Default is ``ERROR``.
|
||
|
||
``compilemessages``
|
||
-------------------
|
||
|
||
.. django-admin:: compilemessages
|
||
|
||
Compiles ``.po`` files created by :djadmin:`makemessages` to ``.mo`` files for
|
||
use with the built-in gettext support. See :doc:`/topics/i18n/index`.
|
||
|
||
.. django-admin-option:: --locale LOCALE, -l LOCALE
|
||
|
||
Specifies the locale(s) to process. If not provided, all locales are processed.
|
||
|
||
.. django-admin-option:: --exclude EXCLUDE, -x EXCLUDE
|
||
|
||
Specifies the locale(s) to exclude from processing. If not provided, no locales
|
||
are excluded.
|
||
|
||
.. django-admin-option:: --use-fuzzy, -f
|
||
|
||
Includes `fuzzy translations`_ into compiled files.
|
||
|
||
Example usage::
|
||
|
||
django-admin compilemessages --locale=pt_BR
|
||
django-admin compilemessages --locale=pt_BR --locale=fr -f
|
||
django-admin compilemessages -l pt_BR
|
||
django-admin compilemessages -l pt_BR -l fr --use-fuzzy
|
||
django-admin compilemessages --exclude=pt_BR
|
||
django-admin compilemessages --exclude=pt_BR --exclude=fr
|
||
django-admin compilemessages -x pt_BR
|
||
django-admin compilemessages -x pt_BR -x fr
|
||
|
||
.. _fuzzy translations: https://www.gnu.org/software/gettext/manual/html_node/Fuzzy-Entries.html
|
||
|
||
.. django-admin-option:: --ignore PATTERN, -i PATTERN
|
||
|
||
Ignores directories matching the given :mod:`glob`-style pattern. Use
|
||
multiple times to ignore more.
|
||
|
||
Example usage::
|
||
|
||
django-admin compilemessages --ignore=cache --ignore=outdated/*/locale
|
||
|
||
``createcachetable``
|
||
--------------------
|
||
|
||
.. django-admin:: createcachetable
|
||
|
||
Creates the cache tables for use with the database cache backend using the
|
||
information from your settings file. See :doc:`/topics/cache` for more
|
||
information.
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database in which the cache table(s) will be created. Defaults to
|
||
``default``.
|
||
|
||
.. django-admin-option:: --dry-run
|
||
|
||
Prints the SQL that would be run without actually running it, so you can
|
||
customize it or use the migrations framework.
|
||
|
||
``dbshell``
|
||
-----------
|
||
|
||
.. django-admin:: dbshell
|
||
|
||
Runs the command-line client for the database engine specified in your
|
||
:setting:`ENGINE <DATABASE-ENGINE>` setting, with the connection parameters
|
||
specified in your :setting:`USER`, :setting:`PASSWORD`, etc., settings.
|
||
|
||
* For PostgreSQL, this runs the ``psql`` command-line client.
|
||
* For MySQL, this runs the ``mysql`` command-line client.
|
||
* For SQLite, this runs the ``sqlite3`` command-line client.
|
||
* For Oracle, this runs the ``sqlplus`` command-line client.
|
||
|
||
This command assumes the programs are on your ``PATH`` so that a call to
|
||
the program name (``psql``, ``mysql``, ``sqlite3``, ``sqlplus``) will find the
|
||
program in the right place. There's no way to specify the location of the
|
||
program manually.
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database onto which to open a shell. Defaults to ``default``.
|
||
|
||
.. django-admin-option:: -- ARGUMENTS
|
||
|
||
.. versionadded:: 3.1
|
||
|
||
Any arguments following a ``--`` divider will be passed on to the underlying
|
||
command-line client. For example, with PostgreSQL you can use the ``psql``
|
||
command's ``-c`` flag to execute a raw SQL query directly:
|
||
|
||
.. console::
|
||
|
||
$ django-admin dbshell -- -c 'select current_user'
|
||
current_user
|
||
--------------
|
||
postgres
|
||
(1 row)
|
||
|
||
On MySQL/MariaDB, you can do this with the ``mysql`` command's ``-e`` flag:
|
||
|
||
.. console::
|
||
|
||
$ django-admin dbshell -- -e "select user()"
|
||
+----------------------+
|
||
| user() |
|
||
+----------------------+
|
||
| djangonaut@localhost |
|
||
+----------------------+
|
||
|
||
.. note::
|
||
|
||
Be aware that not all options set in the :setting:`OPTIONS` part of your
|
||
database configuration in :setting:`DATABASES` are passed to the
|
||
command-line client, e.g. ``'isolation_level'``.
|
||
|
||
``diffsettings``
|
||
----------------
|
||
|
||
.. django-admin:: diffsettings
|
||
|
||
Displays differences between the current settings file and Django's default
|
||
settings (or another settings file specified by :option:`--default`).
|
||
|
||
Settings that don't appear in the defaults are followed by ``"###"``. For
|
||
example, the default settings don't define :setting:`ROOT_URLCONF`, so
|
||
:setting:`ROOT_URLCONF` is followed by ``"###"`` in the output of
|
||
``diffsettings``.
|
||
|
||
.. django-admin-option:: --all
|
||
|
||
Displays all settings, even if they have Django's default value. Such settings
|
||
are prefixed by ``"###"``.
|
||
|
||
.. django-admin-option:: --default MODULE
|
||
|
||
The settings module to compare the current settings against. Leave empty to
|
||
compare against Django's default settings.
|
||
|
||
.. django-admin-option:: --output {hash,unified}
|
||
|
||
Specifies the output format. Available values are ``hash`` and ``unified``.
|
||
``hash`` is the default mode that displays the output that's described above.
|
||
``unified`` displays the output similar to ``diff -u``. Default settings are
|
||
prefixed with a minus sign, followed by the changed setting prefixed with a
|
||
plus sign.
|
||
|
||
``dumpdata``
|
||
------------
|
||
|
||
.. django-admin:: dumpdata [app_label[.ModelName] [app_label[.ModelName] ...]]
|
||
|
||
Outputs to standard output all data in the database associated with the named
|
||
application(s).
|
||
|
||
If no application name is provided, all installed applications will be dumped.
|
||
|
||
The output of ``dumpdata`` can be used as input for :djadmin:`loaddata`.
|
||
|
||
Note that ``dumpdata`` uses the default manager on the model for selecting the
|
||
records to dump. If you're using a :ref:`custom manager <custom-managers>` as
|
||
the default manager and it filters some of the available records, not all of the
|
||
objects will be dumped.
|
||
|
||
.. django-admin-option:: --all, -a
|
||
|
||
Uses Django's base manager, dumping records which might otherwise be filtered
|
||
or modified by a custom manager.
|
||
|
||
.. django-admin-option:: --format FORMAT
|
||
|
||
Specifies the serialization format of the output. Defaults to JSON. Supported
|
||
formats are listed in :ref:`serialization-formats`.
|
||
|
||
.. django-admin-option:: --indent INDENT
|
||
|
||
Specifies the number of indentation spaces to use in the output. Defaults to
|
||
``None`` which displays all data on single line.
|
||
|
||
.. django-admin-option:: --exclude EXCLUDE, -e EXCLUDE
|
||
|
||
Prevents specific applications or models (specified in the form of
|
||
``app_label.ModelName``) from being dumped. If you specify a model name, the
|
||
output will be restricted to that model, rather than the entire application.
|
||
You can also mix application names and model names.
|
||
|
||
If you want to exclude multiple applications, pass ``--exclude`` more than
|
||
once::
|
||
|
||
django-admin dumpdata --exclude=auth --exclude=contenttypes
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database from which data will be dumped. Defaults to ``default``.
|
||
|
||
.. django-admin-option:: --natural-foreign
|
||
|
||
Uses the ``natural_key()`` model method to serialize any foreign key and
|
||
many-to-many relationship to objects of the type that defines the method. If
|
||
you're dumping ``contrib.auth`` ``Permission`` objects or
|
||
``contrib.contenttypes`` ``ContentType`` objects, you should probably use this
|
||
flag. See the :ref:`natural keys <topics-serialization-natural-keys>`
|
||
documentation for more details on this and the next option.
|
||
|
||
.. django-admin-option:: --natural-primary
|
||
|
||
Omits the primary key in the serialized data of this object since it can be
|
||
calculated during deserialization.
|
||
|
||
.. django-admin-option:: --pks PRIMARY_KEYS
|
||
|
||
Outputs only the objects specified by a comma separated list of primary keys.
|
||
This is only available when dumping one model. By default, all the records of
|
||
the model are output.
|
||
|
||
.. django-admin-option:: --output OUTPUT, -o OUTPUT
|
||
|
||
Specifies a file to write the serialized data to. By default, the data goes to
|
||
standard output.
|
||
|
||
When this option is set and ``--verbosity`` is greater than 0 (the default), a
|
||
progress bar is shown in the terminal.
|
||
|
||
``flush``
|
||
---------
|
||
|
||
.. django-admin:: flush
|
||
|
||
Removes all data from the database and re-executes any post-synchronization
|
||
handlers. The table of which migrations have been applied is not cleared.
|
||
|
||
If you would rather start from an empty database and re-run all migrations, you
|
||
should drop and recreate the database and then run :djadmin:`migrate` instead.
|
||
|
||
.. django-admin-option:: --noinput, --no-input
|
||
|
||
Suppresses all user prompts.
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database to flush. Defaults to ``default``.
|
||
|
||
``inspectdb``
|
||
-------------
|
||
|
||
.. django-admin:: inspectdb [table [table ...]]
|
||
|
||
Introspects the database tables in the database pointed-to by the
|
||
:setting:`NAME` setting and outputs a Django model module (a ``models.py``
|
||
file) to standard output.
|
||
|
||
You may choose what tables or views to inspect by passing their names as
|
||
arguments. If no arguments are provided, models are created for views only if
|
||
the :option:`--include-views` option is used. Models for partition tables are
|
||
created on PostgreSQL if the :option:`--include-partitions` option is used.
|
||
|
||
Use this if you have a legacy database with which you'd like to use Django.
|
||
The script will inspect the database and create a model for each table within
|
||
it.
|
||
|
||
As you might expect, the created models will have an attribute for every field
|
||
in the table. Note that ``inspectdb`` has a few special cases in its field-name
|
||
output:
|
||
|
||
* If ``inspectdb`` cannot map a column's type to a model field type, it'll
|
||
use ``TextField`` and will insert the Python comment
|
||
``'This field type is a guess.'`` next to the field in the generated
|
||
model. The recognized fields may depend on apps listed in
|
||
:setting:`INSTALLED_APPS`. For example, :mod:`django.contrib.postgres` adds
|
||
recognition for several PostgreSQL-specific field types.
|
||
|
||
* If the database column name is a Python reserved word (such as
|
||
``'pass'``, ``'class'`` or ``'for'``), ``inspectdb`` will append
|
||
``'_field'`` to the attribute name. For example, if a table has a column
|
||
``'for'``, the generated model will have a field ``'for_field'``, with
|
||
the ``db_column`` attribute set to ``'for'``. ``inspectdb`` will insert
|
||
the Python comment
|
||
``'Field renamed because it was a Python reserved word.'`` next to the
|
||
field.
|
||
|
||
This feature is meant as a shortcut, not as definitive model generation. After
|
||
you run it, you'll want to look over the generated models yourself to make
|
||
customizations. In particular, you'll need to rearrange models' order, so that
|
||
models that refer to other models are ordered properly.
|
||
|
||
Django doesn't create database defaults when a
|
||
:attr:`~django.db.models.Field.default` is specified on a model field.
|
||
Similarly, database defaults aren't translated to model field defaults or
|
||
detected in any fashion by ``inspectdb``.
|
||
|
||
By default, ``inspectdb`` creates unmanaged models. That is, ``managed = False``
|
||
in the model's ``Meta`` class tells Django not to manage each table's creation,
|
||
modification, and deletion. If you do want to allow Django to manage the
|
||
table's lifecycle, you'll need to change the
|
||
:attr:`~django.db.models.Options.managed` option to ``True`` (or remove
|
||
it because ``True`` is its default value).
|
||
|
||
Database-specific notes
|
||
~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Oracle
|
||
^^^^^^
|
||
|
||
* Models are created for materialized views if :option:`--include-views` is
|
||
used.
|
||
|
||
PostgreSQL
|
||
^^^^^^^^^^
|
||
|
||
* Models are created for foreign tables.
|
||
* Models are created for materialized views if
|
||
:option:`--include-views` is used.
|
||
* Models are created for partition tables if
|
||
:option:`--include-partitions` is used.
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database to introspect. Defaults to ``default``.
|
||
|
||
.. django-admin-option:: --include-partitions
|
||
|
||
If this option is provided, models are also created for partitions.
|
||
|
||
Only support for PostgreSQL is implemented.
|
||
|
||
.. django-admin-option:: --include-views
|
||
|
||
If this option is provided, models are also created for database views.
|
||
|
||
``loaddata``
|
||
------------
|
||
|
||
.. django-admin:: loaddata fixture [fixture ...]
|
||
|
||
Searches for and loads the contents of the named fixture into the database.
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database into which the data will be loaded. Defaults to
|
||
``default``.
|
||
|
||
.. django-admin-option:: --ignorenonexistent, -i
|
||
|
||
Ignores fields and models that may have been removed since the fixture was
|
||
originally generated.
|
||
|
||
.. django-admin-option:: --app APP_LABEL
|
||
|
||
Specifies a single app to look for fixtures in rather than looking in all apps.
|
||
|
||
.. django-admin-option:: --format FORMAT
|
||
|
||
Specifies the :ref:`serialization format <serialization-formats>` (e.g.,
|
||
``json`` or ``xml``) for fixtures :ref:`read from stdin
|
||
<loading-fixtures-stdin>`.
|
||
|
||
.. django-admin-option:: --exclude EXCLUDE, -e EXCLUDE
|
||
|
||
Excludes loading the fixtures from the given applications and/or models (in the
|
||
form of ``app_label`` or ``app_label.ModelName``). Use the option multiple
|
||
times to exclude more than one app or model.
|
||
|
||
What's a "fixture"?
|
||
~~~~~~~~~~~~~~~~~~~
|
||
|
||
A *fixture* is a collection of files that contain the serialized contents of
|
||
the database. Each fixture has a unique name, and the files that comprise the
|
||
fixture can be distributed over multiple directories, in multiple applications.
|
||
|
||
Django will search in three locations for fixtures:
|
||
|
||
1. In the ``fixtures`` directory of every installed application
|
||
2. In any directory named in the :setting:`FIXTURE_DIRS` setting
|
||
3. In the literal path named by the fixture
|
||
|
||
Django will load any and all fixtures it finds in these locations that match
|
||
the provided fixture names.
|
||
|
||
If the named fixture has a file extension, only fixtures of that type
|
||
will be loaded. For example::
|
||
|
||
django-admin loaddata mydata.json
|
||
|
||
would only load JSON fixtures called ``mydata``. The fixture extension
|
||
must correspond to the registered name of a
|
||
:ref:`serializer <serialization-formats>` (e.g., ``json`` or ``xml``).
|
||
|
||
If you omit the extensions, Django will search all available fixture types
|
||
for a matching fixture. For example::
|
||
|
||
django-admin loaddata mydata
|
||
|
||
would look for any fixture of any fixture type called ``mydata``. If a fixture
|
||
directory contained ``mydata.json``, that fixture would be loaded
|
||
as a JSON fixture.
|
||
|
||
The fixtures that are named can include directory components. These
|
||
directories will be included in the search path. For example::
|
||
|
||
django-admin loaddata foo/bar/mydata.json
|
||
|
||
would search ``<app_label>/fixtures/foo/bar/mydata.json`` for each installed
|
||
application, ``<dirname>/foo/bar/mydata.json`` for each directory in
|
||
:setting:`FIXTURE_DIRS`, and the literal path ``foo/bar/mydata.json``.
|
||
|
||
When fixture files are processed, the data is saved to the database as is.
|
||
Model defined :meth:`~django.db.models.Model.save` methods are not called, and
|
||
any :data:`~django.db.models.signals.pre_save` or
|
||
:data:`~django.db.models.signals.post_save` signals will be called with
|
||
``raw=True`` since the instance only contains attributes that are local to the
|
||
model. You may, for example, want to disable handlers that access
|
||
related fields that aren't present during fixture loading and would otherwise
|
||
raise an exception::
|
||
|
||
from django.db.models.signals import post_save
|
||
from .models import MyModel
|
||
|
||
def my_handler(**kwargs):
|
||
# disable the handler during fixture loading
|
||
if kwargs['raw']:
|
||
return
|
||
...
|
||
|
||
post_save.connect(my_handler, sender=MyModel)
|
||
|
||
You could also write a decorator to encapsulate this logic::
|
||
|
||
from functools import wraps
|
||
|
||
def disable_for_loaddata(signal_handler):
|
||
"""
|
||
Decorator that turns off signal handlers when loading fixture data.
|
||
"""
|
||
@wraps(signal_handler)
|
||
def wrapper(*args, **kwargs):
|
||
if kwargs['raw']:
|
||
return
|
||
signal_handler(*args, **kwargs)
|
||
return wrapper
|
||
|
||
@disable_for_loaddata
|
||
def my_handler(**kwargs):
|
||
...
|
||
|
||
Just be aware that this logic will disable the signals whenever fixtures are
|
||
deserialized, not just during ``loaddata``.
|
||
|
||
Note that the order in which fixture files are processed is undefined. However,
|
||
all fixture data is installed as a single transaction, so data in
|
||
one fixture can reference data in another fixture. If the database backend
|
||
supports row-level constraints, these constraints will be checked at the
|
||
end of the transaction.
|
||
|
||
The :djadmin:`dumpdata` command can be used to generate input for ``loaddata``.
|
||
|
||
Compressed fixtures
|
||
~~~~~~~~~~~~~~~~~~~
|
||
|
||
Fixtures may be compressed in ``zip``, ``gz``, ``bz2``, ``lzma``, or ``xz``
|
||
format. For example::
|
||
|
||
django-admin loaddata mydata.json
|
||
|
||
would look for any of ``mydata.json``, ``mydata.json.zip``, ``mydata.json.gz``,
|
||
``mydata.json.bz2``, ``mydata.json.lzma``, or ``mydata.json.xz``. The first
|
||
file contained within a compressed archive is used.
|
||
|
||
Note that if two fixtures with the same name but different
|
||
fixture type are discovered (for example, if ``mydata.json`` and
|
||
``mydata.xml.gz`` were found in the same fixture directory), fixture
|
||
installation will be aborted, and any data installed in the call to
|
||
``loaddata`` will be removed from the database.
|
||
|
||
.. admonition:: MySQL with MyISAM and fixtures
|
||
|
||
The MyISAM storage engine of MySQL doesn't support transactions or
|
||
constraints, so if you use MyISAM, you won't get validation of fixture
|
||
data, or a rollback if multiple transaction files are found.
|
||
|
||
.. versionchanged:: 3.2
|
||
|
||
Support for XZ archives (``.xz``) and LZMA archives (``.lzma``) was added.
|
||
|
||
Database-specific fixtures
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
If you're in a multi-database setup, you might have fixture data that
|
||
you want to load onto one database, but not onto another. In this
|
||
situation, you can add a database identifier into the names of your fixtures.
|
||
|
||
For example, if your :setting:`DATABASES` setting has a 'master' database
|
||
defined, name the fixture ``mydata.master.json`` or
|
||
``mydata.master.json.gz`` and the fixture will only be loaded when you
|
||
specify you want to load data into the ``master`` database.
|
||
|
||
.. _loading-fixtures-stdin:
|
||
|
||
Loading fixtures from ``stdin``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
You can use a dash as the fixture name to load input from ``sys.stdin``. For
|
||
example::
|
||
|
||
django-admin loaddata --format=json -
|
||
|
||
When reading from ``stdin``, the :option:`--format <loaddata --format>` option
|
||
is required to specify the :ref:`serialization format <serialization-formats>`
|
||
of the input (e.g., ``json`` or ``xml``).
|
||
|
||
Loading from ``stdin`` is useful with standard input and output redirections.
|
||
For example::
|
||
|
||
django-admin dumpdata --format=json --database=test app_label.ModelName | django-admin loaddata --format=json --database=prod -
|
||
|
||
``makemessages``
|
||
----------------
|
||
|
||
.. django-admin:: makemessages
|
||
|
||
Runs over the entire source tree of the current directory and pulls out all
|
||
strings marked for translation. It creates (or updates) a message file in the
|
||
conf/locale (in the Django tree) or locale (for project and application)
|
||
directory. After making changes to the messages files you need to compile them
|
||
with :djadmin:`compilemessages` for use with the builtin gettext support. See
|
||
the :ref:`i18n documentation <how-to-create-language-files>` for details.
|
||
|
||
This command doesn't require configured settings. However, when settings aren't
|
||
configured, the command can't ignore the :setting:`MEDIA_ROOT` and
|
||
:setting:`STATIC_ROOT` directories or include :setting:`LOCALE_PATHS`.
|
||
|
||
.. django-admin-option:: --all, -a
|
||
|
||
Updates the message files for all available languages.
|
||
|
||
.. django-admin-option:: --extension EXTENSIONS, -e EXTENSIONS
|
||
|
||
Specifies a list of file extensions to examine (default: ``html``, ``txt``,
|
||
``py`` or ``js`` if :option:`--domain` is ``js``).
|
||
|
||
Example usage::
|
||
|
||
django-admin makemessages --locale=de --extension xhtml
|
||
|
||
Separate multiple extensions with commas or use ``-e`` or ``--extension``
|
||
multiple times::
|
||
|
||
django-admin makemessages --locale=de --extension=html,txt --extension xml
|
||
|
||
.. django-admin-option:: --locale LOCALE, -l LOCALE
|
||
|
||
Specifies the locale(s) to process.
|
||
|
||
.. django-admin-option:: --exclude EXCLUDE, -x EXCLUDE
|
||
|
||
Specifies the locale(s) to exclude from processing. If not provided, no locales
|
||
are excluded.
|
||
|
||
Example usage::
|
||
|
||
django-admin makemessages --locale=pt_BR
|
||
django-admin makemessages --locale=pt_BR --locale=fr
|
||
django-admin makemessages -l pt_BR
|
||
django-admin makemessages -l pt_BR -l fr
|
||
django-admin makemessages --exclude=pt_BR
|
||
django-admin makemessages --exclude=pt_BR --exclude=fr
|
||
django-admin makemessages -x pt_BR
|
||
django-admin makemessages -x pt_BR -x fr
|
||
|
||
.. django-admin-option:: --domain DOMAIN, -d DOMAIN
|
||
|
||
Specifies the domain of the messages files. Supported options are:
|
||
|
||
* ``django`` for all ``*.py``, ``*.html`` and ``*.txt`` files (default)
|
||
* ``djangojs`` for ``*.js`` files
|
||
|
||
.. django-admin-option:: --symlinks, -s
|
||
|
||
Follows symlinks to directories when looking for new translation strings.
|
||
|
||
Example usage::
|
||
|
||
django-admin makemessages --locale=de --symlinks
|
||
|
||
.. django-admin-option:: --ignore PATTERN, -i PATTERN
|
||
|
||
Ignores files or directories matching the given :mod:`glob`-style pattern. Use
|
||
multiple times to ignore more.
|
||
|
||
These patterns are used by default: ``'CVS'``, ``'.*'``, ``'*~'``, ``'*.pyc'``.
|
||
|
||
Example usage::
|
||
|
||
django-admin makemessages --locale=en_US --ignore=apps/* --ignore=secret/*.html
|
||
|
||
.. django-admin-option:: --no-default-ignore
|
||
|
||
Disables the default values of ``--ignore``.
|
||
|
||
.. django-admin-option:: --no-wrap
|
||
|
||
Disables breaking long message lines into several lines in language files.
|
||
|
||
.. django-admin-option:: --no-location
|
||
|
||
Suppresses writing '``#: filename:line``’ comment lines in language files.
|
||
Using this option makes it harder for technically skilled translators to
|
||
understand each message's context.
|
||
|
||
.. django-admin-option:: --add-location [{full,file,never}]
|
||
|
||
Controls ``#: filename:line`` comment lines in language files. If the option
|
||
is:
|
||
|
||
* ``full`` (the default if not given): the lines include both file name and
|
||
line number.
|
||
* ``file``: the line number is omitted.
|
||
* ``never``: the lines are suppressed (same as :option:`--no-location`).
|
||
|
||
Requires ``gettext`` 0.19 or newer.
|
||
|
||
.. django-admin-option:: --keep-pot
|
||
|
||
Prevents deleting the temporary ``.pot`` files generated before creating the
|
||
``.po`` file. This is useful for debugging errors which may prevent the final
|
||
language files from being created.
|
||
|
||
.. seealso::
|
||
|
||
See :ref:`customizing-makemessages` for instructions on how to customize
|
||
the keywords that :djadmin:`makemessages` passes to ``xgettext``.
|
||
|
||
``makemigrations``
|
||
------------------
|
||
|
||
.. django-admin:: makemigrations [app_label [app_label ...]]
|
||
|
||
Creates new migrations based on the changes detected to your models.
|
||
Migrations, their relationship with apps and more are covered in depth in
|
||
:doc:`the migrations documentation</topics/migrations>`.
|
||
|
||
Providing one or more app names as arguments will limit the migrations created
|
||
to the app(s) specified and any dependencies needed (the table at the other end
|
||
of a ``ForeignKey``, for example).
|
||
|
||
To add migrations to an app that doesn't have a ``migrations`` directory, run
|
||
``makemigrations`` with the app's ``app_label``.
|
||
|
||
.. django-admin-option:: --noinput, --no-input
|
||
|
||
Suppresses all user prompts. If a suppressed prompt cannot be resolved
|
||
automatically, the command will exit with error code 3.
|
||
|
||
.. django-admin-option:: --empty
|
||
|
||
Outputs an empty migration for the specified apps, for manual editing. This is
|
||
for advanced users and should not be used unless you are familiar with the
|
||
migration format, migration operations, and the dependencies between your
|
||
migrations.
|
||
|
||
.. django-admin-option:: --dry-run
|
||
|
||
Shows what migrations would be made without actually writing any migrations
|
||
files to disk. Using this option along with ``--verbosity 3`` will also show
|
||
the complete migrations files that would be written.
|
||
|
||
.. django-admin-option:: --merge
|
||
|
||
Enables fixing of migration conflicts.
|
||
|
||
.. django-admin-option:: --name NAME, -n NAME
|
||
|
||
Allows naming the generated migration(s) instead of using a generated name. The
|
||
name must be a valid Python :ref:`identifier <python:identifiers>`.
|
||
|
||
.. django-admin-option:: --no-header
|
||
|
||
Generate migration files without Django version and timestamp header.
|
||
|
||
.. django-admin-option:: --check
|
||
|
||
Makes ``makemigrations`` exit with a non-zero status when model changes without
|
||
migrations are detected.
|
||
|
||
.. versionchanged:: 3.2
|
||
|
||
Support for calling ``makemigrations`` without an active database
|
||
connection was added. In that case, check for a consistent migration
|
||
history is skipped.
|
||
|
||
``migrate``
|
||
-----------
|
||
|
||
.. django-admin:: migrate [app_label] [migration_name]
|
||
|
||
Synchronizes the database state with the current set of models and migrations.
|
||
Migrations, their relationship with apps and more are covered in depth in
|
||
:doc:`the migrations documentation</topics/migrations>`.
|
||
|
||
The behavior of this command changes depending on the arguments provided:
|
||
|
||
* No arguments: All apps have all of their migrations run.
|
||
* ``<app_label>``: The specified app has its migrations run, up to the most
|
||
recent migration. This may involve running other apps' migrations too, due
|
||
to dependencies.
|
||
* ``<app_label> <migrationname>``: Brings the database schema to a state where
|
||
the named migration is applied, but no later migrations in the same app are
|
||
applied. This may involve unapplying migrations if you have previously
|
||
migrated past the named migration. You can use a prefix of the migration
|
||
name, e.g. ``0001``, as long as it's unique for the given app name. Use the
|
||
name ``zero`` to migrate all the way back i.e. to revert all applied
|
||
migrations for an app.
|
||
|
||
.. warning::
|
||
|
||
When unapplying migrations, all dependent migrations will also be
|
||
unapplied, regardless of ``<app_label>``. You can use ``--plan`` to check
|
||
which migrations will be unapplied.
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database to migrate. Defaults to ``default``.
|
||
|
||
.. django-admin-option:: --fake
|
||
|
||
Marks the migrations up to the target one (following the rules above) as
|
||
applied, but without actually running the SQL to change your database schema.
|
||
|
||
This is intended for advanced users to manipulate the
|
||
current migration state directly if they're manually applying changes;
|
||
be warned that using ``--fake`` runs the risk of putting the migration state
|
||
table into a state where manual recovery will be needed to make migrations
|
||
run correctly.
|
||
|
||
.. django-admin-option:: --fake-initial
|
||
|
||
Allows Django to skip an app's initial migration if all database tables with
|
||
the names of all models created by all
|
||
:class:`~django.db.migrations.operations.CreateModel` operations in that
|
||
migration already exist. This option is intended for use when first running
|
||
migrations against a database that preexisted the use of migrations. This
|
||
option does not, however, check for matching database schema beyond matching
|
||
table names and so is only safe to use if you are confident that your existing
|
||
schema matches what is recorded in your initial migration.
|
||
|
||
.. django-admin-option:: --plan
|
||
|
||
Shows the migration operations that will be performed for the given ``migrate``
|
||
command.
|
||
|
||
.. django-admin-option:: --run-syncdb
|
||
|
||
Allows creating tables for apps without migrations. While this isn't
|
||
recommended, the migrations framework is sometimes too slow on large projects
|
||
with hundreds of models.
|
||
|
||
.. django-admin-option:: --noinput, --no-input
|
||
|
||
Suppresses all user prompts. An example prompt is asking about removing stale
|
||
content types.
|
||
|
||
.. django-admin-option:: --check
|
||
|
||
.. versionadded:: 3.1
|
||
|
||
Makes ``migrate`` exit with a non-zero status when unapplied migrations are
|
||
detected.
|
||
|
||
``runserver``
|
||
-------------
|
||
|
||
.. django-admin:: runserver [addrport]
|
||
|
||
Starts a lightweight development Web server on the local machine. By default,
|
||
the server runs on port 8000 on the IP address ``127.0.0.1``. You can pass in an
|
||
IP address and port number explicitly.
|
||
|
||
If you run this script as a user with normal privileges (recommended), you
|
||
might not have access to start a port on a low port number. Low port numbers
|
||
are reserved for the superuser (root).
|
||
|
||
This server uses the WSGI application object specified by the
|
||
:setting:`WSGI_APPLICATION` setting.
|
||
|
||
DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through
|
||
security audits or performance tests. (And that's how it's gonna stay. We're in
|
||
the business of making Web frameworks, not Web servers, so improving this
|
||
server to be able to handle a production environment is outside the scope of
|
||
Django.)
|
||
|
||
The development server automatically reloads Python code for each request, as
|
||
needed. You don't need to restart the server for code changes to take effect.
|
||
However, some actions like adding files don't trigger a restart, so you'll
|
||
have to restart the server in these cases.
|
||
|
||
If you're using Linux or MacOS and install both `pywatchman`_ and the
|
||
`Watchman`_ service, kernel signals will be used to autoreload the server
|
||
(rather than polling file modification timestamps each second). This offers
|
||
better performance on large projects, reduced response time after code changes,
|
||
more robust change detection, and a reduction in power usage. Django supports
|
||
``pywatchman`` 1.2.0 and higher.
|
||
|
||
.. admonition:: Large directories with many files may cause performance issues
|
||
|
||
When using Watchman with a project that includes large non-Python
|
||
directories like ``node_modules``, it's advisable to ignore this directory
|
||
for optimal performance. See the `watchman documentation`_ for information
|
||
on how to do this.
|
||
|
||
.. admonition:: Watchman timeout
|
||
|
||
.. envvar:: DJANGO_WATCHMAN_TIMEOUT
|
||
|
||
The default timeout of ``Watchman`` client is 5 seconds. You can change it
|
||
by setting the :envvar:`DJANGO_WATCHMAN_TIMEOUT` environment variable.
|
||
|
||
.. _Watchman: https://facebook.github.io/watchman/
|
||
.. _pywatchman: https://pypi.org/project/pywatchman/
|
||
.. _watchman documentation: https://facebook.github.io/watchman/docs/config#ignore_dirs
|
||
|
||
When you start the server, and each time you change Python code while the
|
||
server is running, the system check framework will check your entire Django
|
||
project for some common errors (see the :djadmin:`check` command). If any
|
||
errors are found, they will be printed to standard output.
|
||
|
||
You can run as many concurrent servers as you want, as long as they're on
|
||
separate ports by executing ``django-admin runserver`` more than once.
|
||
|
||
Note that the default IP address, ``127.0.0.1``, is not accessible from other
|
||
machines on your network. To make your development server viewable to other
|
||
machines on the network, use its own IP address (e.g. ``192.168.2.1``) or
|
||
``0.0.0.0`` or ``::`` (with IPv6 enabled).
|
||
|
||
You can provide an IPv6 address surrounded by brackets
|
||
(e.g. ``[200a::1]:8000``). This will automatically enable IPv6 support.
|
||
|
||
A hostname containing ASCII-only characters can also be used.
|
||
|
||
If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled
|
||
(default in new projects) the :djadmin:`runserver` command will be overridden
|
||
with its own :ref:`runserver<staticfiles-runserver>` command.
|
||
|
||
Logging of each request and response of the server is sent to the
|
||
:ref:`django-server-logger` logger.
|
||
|
||
.. django-admin-option:: --noreload
|
||
|
||
Disables the auto-reloader. This means any Python code changes you make while
|
||
the server is running will *not* take effect if the particular Python modules
|
||
have already been loaded into memory.
|
||
|
||
.. django-admin-option:: --nothreading
|
||
|
||
Disables use of threading in the development server. The server is
|
||
multithreaded by default.
|
||
|
||
.. django-admin-option:: --ipv6, -6
|
||
|
||
Uses IPv6 for the development server. This changes the default IP address from
|
||
``127.0.0.1`` to ``::1``.
|
||
|
||
Examples of using different ports and addresses
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Port 8000 on IP address ``127.0.0.1``::
|
||
|
||
django-admin runserver
|
||
|
||
Port 8000 on IP address ``1.2.3.4``::
|
||
|
||
django-admin runserver 1.2.3.4:8000
|
||
|
||
Port 7000 on IP address ``127.0.0.1``::
|
||
|
||
django-admin runserver 7000
|
||
|
||
Port 7000 on IP address ``1.2.3.4``::
|
||
|
||
django-admin runserver 1.2.3.4:7000
|
||
|
||
Port 8000 on IPv6 address ``::1``::
|
||
|
||
django-admin runserver -6
|
||
|
||
Port 7000 on IPv6 address ``::1``::
|
||
|
||
django-admin runserver -6 7000
|
||
|
||
Port 7000 on IPv6 address ``2001:0db8:1234:5678::9``::
|
||
|
||
django-admin runserver [2001:0db8:1234:5678::9]:7000
|
||
|
||
Port 8000 on IPv4 address of host ``localhost``::
|
||
|
||
django-admin runserver localhost:8000
|
||
|
||
Port 8000 on IPv6 address of host ``localhost``::
|
||
|
||
django-admin runserver -6 localhost:8000
|
||
|
||
Serving static files with the development server
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
By default, the development server doesn't serve any static files for your site
|
||
(such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If
|
||
you want to configure Django to serve static media, read
|
||
:doc:`/howto/static-files/index`.
|
||
|
||
``sendtestemail``
|
||
-----------------
|
||
|
||
.. django-admin:: sendtestemail [email [email ...]]
|
||
|
||
Sends a test email (to confirm email sending through Django is working) to the
|
||
recipient(s) specified. For example::
|
||
|
||
django-admin sendtestemail foo@example.com bar@example.com
|
||
|
||
There are a couple of options, and you may use any combination of them
|
||
together:
|
||
|
||
.. django-admin-option:: --managers
|
||
|
||
Mails the email addresses specified in :setting:`MANAGERS` using
|
||
:meth:`~django.core.mail.mail_managers()`.
|
||
|
||
.. django-admin-option:: --admins
|
||
|
||
Mails the email addresses specified in :setting:`ADMINS` using
|
||
:meth:`~django.core.mail.mail_admins()`.
|
||
|
||
``shell``
|
||
---------
|
||
|
||
.. django-admin:: shell
|
||
|
||
Starts the Python interactive interpreter.
|
||
|
||
.. django-admin-option:: --interface {ipython,bpython,python}, -i {ipython,bpython,python}
|
||
|
||
Specifies the shell to use. By default, Django will use IPython_ or bpython_ if
|
||
either is installed. If both are installed, specify which one you want like so:
|
||
|
||
IPython::
|
||
|
||
django-admin shell -i ipython
|
||
|
||
bpython::
|
||
|
||
django-admin shell -i bpython
|
||
|
||
If you have a "rich" shell installed but want to force use of the "plain"
|
||
Python interpreter, use ``python`` as the interface name, like so::
|
||
|
||
django-admin shell -i python
|
||
|
||
.. _IPython: https://ipython.org/
|
||
.. _bpython: https://bpython-interpreter.org/
|
||
|
||
.. django-admin-option:: --nostartup
|
||
|
||
Disables reading the startup script for the "plain" Python interpreter. By
|
||
default, the script pointed to by the :envvar:`PYTHONSTARTUP` environment
|
||
variable or the ``~/.pythonrc.py`` script is read.
|
||
|
||
.. django-admin-option:: --command COMMAND, -c COMMAND
|
||
|
||
Lets you pass a command as a string to execute it as Django, like so::
|
||
|
||
django-admin shell --command="import django; print(django.__version__)"
|
||
|
||
You can also pass code in on standard input to execute it. For example:
|
||
|
||
.. code-block:: console
|
||
|
||
$ django-admin shell <<EOF
|
||
> import django
|
||
> print(django.__version__)
|
||
> EOF
|
||
|
||
On Windows, the REPL is output due to implementation limits of
|
||
:func:`select.select` on that platform.
|
||
|
||
``showmigrations``
|
||
------------------
|
||
|
||
.. django-admin:: showmigrations [app_label [app_label ...]]
|
||
|
||
Shows all migrations in a project. You can choose from one of two formats:
|
||
|
||
.. django-admin-option:: --list, -l
|
||
|
||
Lists all of the apps Django knows about, the migrations available for each
|
||
app, and whether or not each migration is applied (marked by an ``[X]`` next to
|
||
the migration name). For a ``--verbosity`` of 2 and above, the applied
|
||
datetimes are also shown.
|
||
|
||
Apps without migrations are also listed, but have ``(no migrations)`` printed
|
||
under them.
|
||
|
||
This is the default output format.
|
||
|
||
.. django-admin-option:: --plan, -p
|
||
|
||
Shows the migration plan Django will follow to apply migrations. Like
|
||
``--list``, applied migrations are marked by an ``[X]``. For a ``--verbosity``
|
||
of 2 and above, all dependencies of a migration will also be shown.
|
||
|
||
``app_label``\s arguments limit the output, however, dependencies of provided
|
||
apps may also be included.
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database to examine. Defaults to ``default``.
|
||
|
||
``sqlflush``
|
||
------------
|
||
|
||
.. django-admin:: sqlflush
|
||
|
||
Prints the SQL statements that would be executed for the :djadmin:`flush`
|
||
command.
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database for which to print the SQL. Defaults to ``default``.
|
||
|
||
``sqlmigrate``
|
||
--------------
|
||
|
||
.. django-admin:: sqlmigrate app_label migration_name
|
||
|
||
Prints the SQL for the named migration. This requires an active database
|
||
connection, which it will use to resolve constraint names; this means you must
|
||
generate the SQL against a copy of the database you wish to later apply it on.
|
||
|
||
Note that ``sqlmigrate`` doesn't colorize its output.
|
||
|
||
.. django-admin-option:: --backwards
|
||
|
||
Generates the SQL for unapplying the migration. By default, the SQL created is
|
||
for running the migration in the forwards direction.
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database for which to generate the SQL. Defaults to ``default``.
|
||
|
||
``sqlsequencereset``
|
||
--------------------
|
||
|
||
.. django-admin:: sqlsequencereset app_label [app_label ...]
|
||
|
||
Prints the SQL statements for resetting sequences for the given app name(s).
|
||
|
||
Sequences are indexes used by some database engines to track the next available
|
||
number for automatically incremented fields.
|
||
|
||
Use this command to generate SQL which will fix cases where a sequence is out
|
||
of sync with its automatically incremented field data.
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database for which to print the SQL. Defaults to ``default``.
|
||
|
||
``squashmigrations``
|
||
--------------------
|
||
|
||
.. django-admin:: squashmigrations app_label [start_migration_name] migration_name
|
||
|
||
Squashes the migrations for ``app_label`` up to and including ``migration_name``
|
||
down into fewer migrations, if possible. The resulting squashed migrations
|
||
can live alongside the unsquashed ones safely. For more information,
|
||
please read :ref:`migration-squashing`.
|
||
|
||
When ``start_migration_name`` is given, Django will only include migrations
|
||
starting from and including this migration. This helps to mitigate the
|
||
squashing limitation of :class:`~django.db.migrations.operations.RunPython` and
|
||
:class:`django.db.migrations.operations.RunSQL` migration operations.
|
||
|
||
.. django-admin-option:: --no-optimize
|
||
|
||
Disables the optimizer when generating a squashed migration. By default, Django
|
||
will try to optimize the operations in your migrations to reduce the size of
|
||
the resulting file. Use this option if this process is failing or creating
|
||
incorrect migrations, though please also file a Django bug report about the
|
||
behavior, as optimization is meant to be safe.
|
||
|
||
.. django-admin-option:: --noinput, --no-input
|
||
|
||
Suppresses all user prompts.
|
||
|
||
.. django-admin-option:: --squashed-name SQUASHED_NAME
|
||
|
||
Sets the name of the squashed migration. When omitted, the name is based on the
|
||
first and last migration, with ``_squashed_`` in between.
|
||
|
||
.. django-admin-option:: --no-header
|
||
|
||
Generate squashed migration file without Django version and timestamp header.
|
||
|
||
``startapp``
|
||
------------
|
||
|
||
.. django-admin:: startapp name [directory]
|
||
|
||
Creates a Django app directory structure for the given app name in the current
|
||
directory or the given destination.
|
||
|
||
By default, :source:`the new directory <django/conf/app_template>` contains a
|
||
``models.py`` file and other app template files. If only the app name is given,
|
||
the app directory will be created in the current working directory.
|
||
|
||
If the optional destination is provided, Django will use that existing
|
||
directory rather than creating a new one. You can use '.' to denote the current
|
||
working directory.
|
||
|
||
For example::
|
||
|
||
django-admin startapp myapp /Users/jezdez/Code/myapp
|
||
|
||
.. _custom-app-and-project-templates:
|
||
|
||
.. django-admin-option:: --template TEMPLATE
|
||
|
||
Provides the path to a directory with a custom app template file, or a path to
|
||
an uncompressed archive (``.tar``) or a compressed archive (``.tar.gz``,
|
||
``.tar.bz2``, ``.tar.xz``, ``.tar.lzma``, ``.tgz``, ``.tbz2``, ``.txz``,
|
||
``.tlz``, ``.zip``) containing the app template files.
|
||
|
||
For example, this would look for an app template in the given directory when
|
||
creating the ``myapp`` app::
|
||
|
||
django-admin startapp --template=/Users/jezdez/Code/my_app_template myapp
|
||
|
||
Django will also accept URLs (``http``, ``https``, ``ftp``) to compressed
|
||
archives with the app template files, downloading and extracting them on the
|
||
fly.
|
||
|
||
For example, taking advantage of GitHub's feature to expose repositories as
|
||
zip files, you can use a URL like::
|
||
|
||
django-admin startapp --template=https://github.com/githubuser/django-app-template/archive/master.zip myapp
|
||
|
||
.. django-admin-option:: --extension EXTENSIONS, -e EXTENSIONS
|
||
|
||
Specifies which file extensions in the app template should be rendered with the
|
||
template engine. Defaults to ``py``.
|
||
|
||
.. django-admin-option:: --name FILES, -n FILES
|
||
|
||
Specifies which files in the app template (in addition to those matching
|
||
``--extension``) should be rendered with the template engine. Defaults to an
|
||
empty list.
|
||
|
||
The :class:`template context <django.template.Context>` used for all matching
|
||
files is:
|
||
|
||
- Any option passed to the ``startapp`` command (among the command's supported
|
||
options)
|
||
- ``app_name`` -- the app name as passed to the command
|
||
- ``app_directory`` -- the full path of the newly created app
|
||
- ``camel_case_app_name`` -- the app name in camel case format
|
||
- ``docs_version`` -- the version of the documentation: ``'dev'`` or ``'1.x'``
|
||
- ``django_version`` -- the version of Django, e.g. ``'2.0.3'``
|
||
|
||
.. _render_warning:
|
||
|
||
.. warning::
|
||
|
||
When the app template files are rendered with the Django template
|
||
engine (by default all ``*.py`` files), Django will also replace all
|
||
stray template variables contained. For example, if one of the Python files
|
||
contains a docstring explaining a particular feature related
|
||
to template rendering, it might result in an incorrect example.
|
||
|
||
To work around this problem, you can use the :ttag:`templatetag`
|
||
template tag to "escape" the various parts of the template syntax.
|
||
|
||
In addition, to allow Python template files that contain Django template
|
||
language syntax while also preventing packaging systems from trying to
|
||
byte-compile invalid ``*.py`` files, template files ending with ``.py-tpl``
|
||
will be renamed to ``.py``.
|
||
|
||
``startproject``
|
||
----------------
|
||
|
||
.. django-admin:: startproject name [directory]
|
||
|
||
Creates a Django project directory structure for the given project name in
|
||
the current directory or the given destination.
|
||
|
||
By default, :source:`the new directory <django/conf/project_template>` contains
|
||
``manage.py`` and a project package (containing a ``settings.py`` and other
|
||
files).
|
||
|
||
If only the project name is given, both the project directory and project
|
||
package will be named ``<projectname>`` and the project directory
|
||
will be created in the current working directory.
|
||
|
||
If the optional destination is provided, Django will use that existing
|
||
directory as the project directory, and create ``manage.py`` and the project
|
||
package within it. Use '.' to denote the current working directory.
|
||
|
||
For example::
|
||
|
||
django-admin startproject myproject /Users/jezdez/Code/myproject_repo
|
||
|
||
.. django-admin-option:: --template TEMPLATE
|
||
|
||
Specifies a directory, file path, or URL of a custom project template. See the
|
||
:option:`startapp --template` documentation for examples and usage.
|
||
|
||
.. django-admin-option:: --extension EXTENSIONS, -e EXTENSIONS
|
||
|
||
Specifies which file extensions in the project template should be rendered with
|
||
the template engine. Defaults to ``py``.
|
||
|
||
.. django-admin-option:: --name FILES, -n FILES
|
||
|
||
Specifies which files in the project template (in addition to those matching
|
||
``--extension``) should be rendered with the template engine. Defaults to an
|
||
empty list.
|
||
|
||
The :class:`template context <django.template.Context>` used is:
|
||
|
||
- Any option passed to the ``startproject`` command (among the command's
|
||
supported options)
|
||
- ``project_name`` -- the project name as passed to the command
|
||
- ``project_directory`` -- the full path of the newly created project
|
||
- ``secret_key`` -- a random key for the :setting:`SECRET_KEY` setting
|
||
- ``docs_version`` -- the version of the documentation: ``'dev'`` or ``'1.x'``
|
||
- ``django_version`` -- the version of Django, e.g. ``'2.0.3'``
|
||
|
||
Please also see the :ref:`rendering warning <render_warning>` as mentioned
|
||
for :djadmin:`startapp`.
|
||
|
||
``test``
|
||
--------
|
||
|
||
.. django-admin:: test [test_label [test_label ...]]
|
||
|
||
Runs tests for all installed apps. See :doc:`/topics/testing/index` for more
|
||
information.
|
||
|
||
.. django-admin-option:: --failfast
|
||
|
||
Stops running tests and reports the failure immediately after a test fails.
|
||
|
||
.. django-admin-option:: --testrunner TESTRUNNER
|
||
|
||
Controls the test runner class that is used to execute tests. This value
|
||
overrides the value provided by the :setting:`TEST_RUNNER` setting.
|
||
|
||
.. django-admin-option:: --noinput, --no-input
|
||
|
||
Suppresses all user prompts. A typical prompt is a warning about deleting an
|
||
existing test database.
|
||
|
||
Test runner options
|
||
~~~~~~~~~~~~~~~~~~~
|
||
|
||
The ``test`` command receives options on behalf of the specified
|
||
:option:`--testrunner`. These are the options of the default test runner:
|
||
:class:`~django.test.runner.DiscoverRunner`.
|
||
|
||
.. django-admin-option:: --keepdb
|
||
|
||
Preserves the test database between test runs. This has the advantage of
|
||
skipping both the create and destroy actions which can greatly decrease the
|
||
time to run tests, especially those in a large test suite. If the test database
|
||
does not exist, it will be created on the first run and then preserved for each
|
||
subsequent run. Unless the :setting:`MIGRATE <TEST_MIGRATE>` test setting is
|
||
``False``, any unapplied migrations will also be applied to the test database
|
||
before running the test suite.
|
||
|
||
.. django-admin-option:: --reverse, -r
|
||
|
||
Sorts test cases in the opposite execution order. This may help in debugging
|
||
the side effects of tests that aren't properly isolated. :ref:`Grouping by test
|
||
class <order-of-tests>` is preserved when using this option.
|
||
|
||
.. django-admin-option:: --debug-mode
|
||
|
||
Sets the :setting:`DEBUG` setting to ``True`` prior to running tests. This may
|
||
help troubleshoot test failures.
|
||
|
||
.. django-admin-option:: --debug-sql, -d
|
||
|
||
Enables :ref:`SQL logging <django-db-logger>` for failing tests. If
|
||
``--verbosity`` is ``2``, then queries in passing tests are also output.
|
||
|
||
.. django-admin-option:: --parallel [N]
|
||
|
||
.. envvar:: DJANGO_TEST_PROCESSES
|
||
|
||
Runs tests in separate parallel processes. Since modern processors have
|
||
multiple cores, this allows running tests significantly faster.
|
||
|
||
By default ``--parallel`` runs one process per core according to
|
||
:func:`multiprocessing.cpu_count()`. You can adjust the number of processes
|
||
either by providing it as the option's value, e.g. ``--parallel=4``, or by
|
||
setting the :envvar:`DJANGO_TEST_PROCESSES` environment variable.
|
||
|
||
Django distributes test cases — :class:`unittest.TestCase` subclasses — to
|
||
subprocesses. If there are fewer test cases than configured processes, Django
|
||
will reduce the number of processes accordingly.
|
||
|
||
Each process gets its own database. You must ensure that different test cases
|
||
don't access the same resources. For instance, test cases that touch the
|
||
filesystem should create a temporary directory for their own use.
|
||
|
||
.. note::
|
||
|
||
If you have test classes that cannot be run in parallel, you can use
|
||
``SerializeMixin`` to run them sequentially. See :ref:`Enforce running test
|
||
classes sequentially <topics-testing-enforce-run-sequentially>`.
|
||
|
||
This option requires the third-party ``tblib`` package to display tracebacks
|
||
correctly:
|
||
|
||
.. code-block:: console
|
||
|
||
$ python -m pip install tblib
|
||
|
||
This feature isn't available on Windows. It doesn't work with the Oracle
|
||
database backend either.
|
||
|
||
If you want to use :mod:`pdb` while debugging tests, you must disable parallel
|
||
execution (``--parallel=1``). You'll see something like ``bdb.BdbQuit`` if you
|
||
don't.
|
||
|
||
.. warning::
|
||
|
||
When test parallelization is enabled and a test fails, Django may be
|
||
unable to display the exception traceback. This can make debugging
|
||
difficult. If you encounter this problem, run the affected test without
|
||
parallelization to see the traceback of the failure.
|
||
|
||
This is a known limitation. It arises from the need to serialize objects
|
||
in order to exchange them between processes. See
|
||
:ref:`python:pickle-picklable` for details.
|
||
|
||
.. option:: --tag TAGS
|
||
|
||
Runs only tests :ref:`marked with the specified tags <topics-tagging-tests>`.
|
||
May be specified multiple times and combined with :option:`test --exclude-tag`.
|
||
|
||
.. option:: --exclude-tag EXCLUDE_TAGS
|
||
|
||
Excludes tests :ref:`marked with the specified tags <topics-tagging-tests>`.
|
||
May be specified multiple times and combined with :option:`test --tag`.
|
||
|
||
.. django-admin-option:: -k TEST_NAME_PATTERNS
|
||
|
||
Runs test methods and classes matching test name patterns, in the same way as
|
||
:option:`unittest's -k option<unittest.-k>`. Can be specified multiple times.
|
||
|
||
.. admonition:: Python 3.7 and later
|
||
|
||
This feature is only available for Python 3.7 and later.
|
||
|
||
.. django-admin-option:: --pdb
|
||
|
||
Spawns a ``pdb`` debugger at each test error or failure. If you have it
|
||
installed, ``ipdb`` is used instead.
|
||
|
||
.. django-admin-option:: --buffer, -b
|
||
|
||
.. versionadded:: 3.1
|
||
|
||
Discards output (``stdout`` and ``stderr``) for passing tests, in the same way
|
||
as :option:`unittest's --buffer option<unittest.-b>`.
|
||
|
||
.. django-admin-option:: --no-faulthandler
|
||
|
||
.. versionadded:: 3.2
|
||
|
||
Django automatically calls :func:`faulthandler.enable()` when starting the
|
||
tests, which allows it to print a traceback if the interpreter crashes. Pass
|
||
``--no-faulthandler`` to disable this behavior.
|
||
|
||
.. django-admin-option:: --timing
|
||
|
||
.. versionadded:: 3.2
|
||
|
||
Outputs timings, including including database setup and total run time.
|
||
|
||
``testserver``
|
||
--------------
|
||
|
||
.. django-admin:: testserver [fixture [fixture ...]]
|
||
|
||
Runs a Django development server (as in :djadmin:`runserver`) using data from
|
||
the given fixture(s).
|
||
|
||
For example, this command::
|
||
|
||
django-admin testserver mydata.json
|
||
|
||
...would perform the following steps:
|
||
|
||
#. Create a test database, as described in :ref:`the-test-database`.
|
||
#. Populate the test database with fixture data from the given fixtures.
|
||
(For more on fixtures, see the documentation for :djadmin:`loaddata` above.)
|
||
#. Runs the Django development server (as in :djadmin:`runserver`), pointed at
|
||
this newly created test database instead of your production database.
|
||
|
||
This is useful in a number of ways:
|
||
|
||
* When you're writing :doc:`unit tests </topics/testing/overview>` of how your views
|
||
act with certain fixture data, you can use ``testserver`` to interact with
|
||
the views in a Web browser, manually.
|
||
|
||
* Let's say you're developing your Django application and have a "pristine"
|
||
copy of a database that you'd like to interact with. You can dump your
|
||
database to a fixture (using the :djadmin:`dumpdata` command, explained
|
||
above), then use ``testserver`` to run your Web application with that data.
|
||
With this arrangement, you have the flexibility of messing up your data
|
||
in any way, knowing that whatever data changes you're making are only
|
||
being made to a test database.
|
||
|
||
Note that this server does *not* automatically detect changes to your Python
|
||
source code (as :djadmin:`runserver` does). It does, however, detect changes to
|
||
templates.
|
||
|
||
.. django-admin-option:: --addrport ADDRPORT
|
||
|
||
Specifies a different port, or IP address and port, from the default of
|
||
``127.0.0.1:8000``. This value follows exactly the same format and serves
|
||
exactly the same function as the argument to the :djadmin:`runserver` command.
|
||
|
||
Examples:
|
||
|
||
To run the test server on port 7000 with ``fixture1`` and ``fixture2``::
|
||
|
||
django-admin testserver --addrport 7000 fixture1 fixture2
|
||
django-admin testserver fixture1 fixture2 --addrport 7000
|
||
|
||
(The above statements are equivalent. We include both of them to demonstrate
|
||
that it doesn't matter whether the options come before or after the fixture
|
||
arguments.)
|
||
|
||
To run on 1.2.3.4:7000 with a ``test`` fixture::
|
||
|
||
django-admin testserver --addrport 1.2.3.4:7000 test
|
||
|
||
.. django-admin-option:: --noinput, --no-input
|
||
|
||
Suppresses all user prompts. A typical prompt is a warning about deleting an
|
||
existing test database.
|
||
|
||
Commands provided by applications
|
||
=================================
|
||
|
||
Some commands are only available when the ``django.contrib`` application that
|
||
:doc:`implements </howto/custom-management-commands>` them has been
|
||
:setting:`enabled <INSTALLED_APPS>`. This section describes them grouped by
|
||
their application.
|
||
|
||
``django.contrib.auth``
|
||
-----------------------
|
||
|
||
``changepassword``
|
||
~~~~~~~~~~~~~~~~~~
|
||
|
||
.. django-admin:: changepassword [<username>]
|
||
|
||
This command is only available if Django's :doc:`authentication system
|
||
</topics/auth/index>` (``django.contrib.auth``) is installed.
|
||
|
||
Allows changing a user's password. It prompts you to enter a new password twice
|
||
for the given user. If the entries are identical, this immediately becomes the
|
||
new password. If you do not supply a user, the command will attempt to change
|
||
the password whose username matches the current user.
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database to query for the user. Defaults to ``default``.
|
||
|
||
Example usage::
|
||
|
||
django-admin changepassword ringo
|
||
|
||
``createsuperuser``
|
||
~~~~~~~~~~~~~~~~~~~
|
||
|
||
.. django-admin:: createsuperuser
|
||
|
||
.. envvar:: DJANGO_SUPERUSER_PASSWORD
|
||
|
||
This command is only available if Django's :doc:`authentication system
|
||
</topics/auth/index>` (``django.contrib.auth``) is installed.
|
||
|
||
Creates a superuser account (a user who has all permissions). This is
|
||
useful if you need to create an initial superuser account or if you need to
|
||
programmatically generate superuser accounts for your site(s).
|
||
|
||
When run interactively, this command will prompt for a password for
|
||
the new superuser account. When run non-interactively, you can provide
|
||
a password by setting the :envvar:`DJANGO_SUPERUSER_PASSWORD` environment
|
||
variable. Otherwise, no password will be set, and the superuser account will
|
||
not be able to log in until a password has been manually set for it.
|
||
|
||
In non-interactive mode, the
|
||
:attr:`~django.contrib.auth.models.CustomUser.USERNAME_FIELD` and required
|
||
fields (listed in
|
||
:attr:`~django.contrib.auth.models.CustomUser.REQUIRED_FIELDS`) fall back to
|
||
``DJANGO_SUPERUSER_<uppercase_field_name>`` environment variables, unless they
|
||
are overridden by a command line argument. For example, to provide an ``email``
|
||
field, you can use ``DJANGO_SUPERUSER_EMAIL`` environment variable.
|
||
|
||
.. django-admin-option:: --noinput, --no-input
|
||
|
||
Suppresses all user prompts. If a suppressed prompt cannot be resolved
|
||
automatically, the command will exit with error code 1.
|
||
|
||
.. django-admin-option:: --username USERNAME
|
||
.. django-admin-option:: --email EMAIL
|
||
|
||
The username and email address for the new account can be supplied by
|
||
using the ``--username`` and ``--email`` arguments on the command
|
||
line. If either of those is not supplied, ``createsuperuser`` will prompt for
|
||
it when running interactively.
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database into which the superuser object will be saved.
|
||
|
||
You can subclass the management command and override ``get_input_data()`` if you
|
||
want to customize data input and validation. Consult the source code for
|
||
details on the existing implementation and the method's parameters. For example,
|
||
it could be useful if you have a ``ForeignKey`` in
|
||
:attr:`~django.contrib.auth.models.CustomUser.REQUIRED_FIELDS` and want to
|
||
allow creating an instance instead of entering the primary key of an existing
|
||
instance.
|
||
|
||
``django.contrib.contenttypes``
|
||
-------------------------------
|
||
|
||
``remove_stale_contenttypes``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
.. django-admin:: remove_stale_contenttypes
|
||
|
||
This command is only available if Django's :doc:`contenttypes app
|
||
</ref/contrib/contenttypes>` (:mod:`django.contrib.contenttypes`) is installed.
|
||
|
||
Deletes stale content types (from deleted models) in your database. Any objects
|
||
that depend on the deleted content types will also be deleted. A list of
|
||
deleted objects will be displayed before you confirm it's okay to proceed with
|
||
the deletion.
|
||
|
||
.. django-admin-option:: --database DATABASE
|
||
|
||
Specifies the database to use. Defaults to ``default``.
|
||
|
||
.. django-admin-option:: --include-stale-apps
|
||
|
||
.. versionadded:: 3.1
|
||
|
||
Deletes stale content types including ones from previously installed apps that
|
||
have been removed from :setting:`INSTALLED_APPS`. Defaults to ``False``.
|
||
|
||
``django.contrib.gis``
|
||
----------------------
|
||
|
||
``ogrinspect``
|
||
~~~~~~~~~~~~~~
|
||
|
||
This command is only available if :doc:`GeoDjango </ref/contrib/gis/index>`
|
||
(``django.contrib.gis``) is installed.
|
||
|
||
Please refer to its :djadmin:`description <ogrinspect>` in the GeoDjango
|
||
documentation.
|
||
|
||
``django.contrib.sessions``
|
||
---------------------------
|
||
|
||
``clearsessions``
|
||
~~~~~~~~~~~~~~~~~
|
||
|
||
.. django-admin:: clearsessions
|
||
|
||
Can be run as a cron job or directly to clean out expired sessions.
|
||
|
||
``django.contrib.sitemaps``
|
||
---------------------------
|
||
|
||
``ping_google``
|
||
~~~~~~~~~~~~~~~
|
||
|
||
This command is only available if the :doc:`Sitemaps framework
|
||
</ref/contrib/sitemaps>` (``django.contrib.sitemaps``) is installed.
|
||
|
||
Please refer to its :djadmin:`description <ping_google>` in the Sitemaps
|
||
documentation.
|
||
|
||
``django.contrib.staticfiles``
|
||
------------------------------
|
||
|
||
``collectstatic``
|
||
~~~~~~~~~~~~~~~~~
|
||
|
||
This command is only available if the :doc:`static files application
|
||
</howto/static-files/index>` (``django.contrib.staticfiles``) is installed.
|
||
|
||
Please refer to its :djadmin:`description <collectstatic>` in the
|
||
:doc:`staticfiles </ref/contrib/staticfiles>` documentation.
|
||
|
||
``findstatic``
|
||
~~~~~~~~~~~~~~
|
||
|
||
This command is only available if the :doc:`static files application
|
||
</howto/static-files/index>` (``django.contrib.staticfiles``) is installed.
|
||
|
||
Please refer to its :djadmin:`description <findstatic>` in the :doc:`staticfiles
|
||
</ref/contrib/staticfiles>` documentation.
|
||
|
||
Default options
|
||
===============
|
||
|
||
.. program:: None
|
||
|
||
Although some commands may allow their own custom options, every command
|
||
allows for the following options:
|
||
|
||
.. django-admin-option:: --pythonpath PYTHONPATH
|
||
|
||
Adds the given filesystem path to the Python `import search path`_. If this
|
||
isn't provided, ``django-admin`` will use the :envvar:`PYTHONPATH` environment
|
||
variable.
|
||
|
||
This option is unnecessary in ``manage.py``, because it takes care of setting
|
||
the Python path for you.
|
||
|
||
Example usage::
|
||
|
||
django-admin migrate --pythonpath='/home/djangoprojects/myproject'
|
||
|
||
.. _import search path: https://www.diveinto.org/python3/your-first-python-program.html#importsearchpath
|
||
|
||
.. django-admin-option:: --settings SETTINGS
|
||
|
||
Specifies the settings module to use. The settings module should be in Python
|
||
package syntax, e.g. ``mysite.settings``. If this isn't provided,
|
||
``django-admin`` will use the :envvar:`DJANGO_SETTINGS_MODULE` environment
|
||
variable.
|
||
|
||
This option is unnecessary in ``manage.py``, because it uses
|
||
``settings.py`` from the current project by default.
|
||
|
||
Example usage::
|
||
|
||
django-admin migrate --settings=mysite.settings
|
||
|
||
.. django-admin-option:: --traceback
|
||
|
||
Displays a full stack trace when a :exc:`~django.core.management.CommandError`
|
||
is raised. By default, ``django-admin`` will show an error message when a
|
||
``CommandError`` occurs and a full stack trace for any other exception.
|
||
|
||
Example usage::
|
||
|
||
django-admin migrate --traceback
|
||
|
||
.. django-admin-option:: --verbosity {0,1,2,3}, -v {0,1,2,3}
|
||
|
||
Specifies the amount of notification and debug information that a command
|
||
should print to the console.
|
||
|
||
* ``0`` means no output.
|
||
* ``1`` means normal output (default).
|
||
* ``2`` means verbose output.
|
||
* ``3`` means *very* verbose output.
|
||
|
||
Example usage::
|
||
|
||
django-admin migrate --verbosity 2
|
||
|
||
.. django-admin-option:: --no-color
|
||
|
||
Disables colorized command output. Some commands format their output to be
|
||
colorized. For example, errors will be printed to the console in red and SQL
|
||
statements will be syntax highlighted.
|
||
|
||
Example usage::
|
||
|
||
django-admin runserver --no-color
|
||
|
||
.. django-admin-option:: --force-color
|
||
|
||
Forces colorization of the command output if it would otherwise be disabled
|
||
as discussed in :ref:`syntax-coloring`. For example, you may want to pipe
|
||
colored output to another command.
|
||
|
||
.. django-admin-option:: --skip-checks
|
||
|
||
Skips running system checks prior to running the command. This option is only
|
||
available if the
|
||
:attr:`~django.core.management.BaseCommand.requires_system_checks` command
|
||
attribute is not an empty list or tuple.
|
||
|
||
Example usage::
|
||
|
||
django-admin migrate --skip-checks
|
||
|
||
Extra niceties
|
||
==============
|
||
|
||
.. _syntax-coloring:
|
||
|
||
Syntax coloring
|
||
---------------
|
||
|
||
.. envvar:: DJANGO_COLORS
|
||
|
||
The ``django-admin`` / ``manage.py`` commands will use pretty
|
||
color-coded output if your terminal supports ANSI-colored output. It
|
||
won't use the color codes if you're piping the command's output to
|
||
another program unless the :option:`--force-color` option is used.
|
||
|
||
Under Windows, the native console doesn't support ANSI escape sequences so by
|
||
default there is no color output. But you can install the `ANSICON`_
|
||
third-party tool, the Django commands will detect its presence and will make
|
||
use of its services to color output just like on Unix-based platforms.
|
||
|
||
The colors used for syntax highlighting can be customized. Django
|
||
ships with three color palettes:
|
||
|
||
* ``dark``, suited to terminals that show white text on a black
|
||
background. This is the default palette.
|
||
|
||
* ``light``, suited to terminals that show black text on a white
|
||
background.
|
||
|
||
* ``nocolor``, which disables syntax highlighting.
|
||
|
||
You select a palette by setting a :envvar:`DJANGO_COLORS` environment
|
||
variable to specify the palette you want to use. For example, to
|
||
specify the ``light`` palette under a Unix or OS/X BASH shell, you
|
||
would run the following at a command prompt::
|
||
|
||
export DJANGO_COLORS="light"
|
||
|
||
You can also customize the colors that are used. Django specifies a
|
||
number of roles in which color is used:
|
||
|
||
* ``error`` - A major error.
|
||
* ``notice`` - A minor error.
|
||
* ``success`` - A success.
|
||
* ``warning`` - A warning.
|
||
* ``sql_field`` - The name of a model field in SQL.
|
||
* ``sql_coltype`` - The type of a model field in SQL.
|
||
* ``sql_keyword`` - An SQL keyword.
|
||
* ``sql_table`` - The name of a model in SQL.
|
||
* ``http_info`` - A 1XX HTTP Informational server response.
|
||
* ``http_success`` - A 2XX HTTP Success server response.
|
||
* ``http_not_modified`` - A 304 HTTP Not Modified server response.
|
||
* ``http_redirect`` - A 3XX HTTP Redirect server response other than 304.
|
||
* ``http_not_found`` - A 404 HTTP Not Found server response.
|
||
* ``http_bad_request`` - A 4XX HTTP Bad Request server response other than 404.
|
||
* ``http_server_error`` - A 5XX HTTP Server Error response.
|
||
* ``migrate_heading`` - A heading in a migrations management command.
|
||
* ``migrate_label`` - A migration name.
|
||
|
||
Each of these roles can be assigned a specific foreground and
|
||
background color, from the following list:
|
||
|
||
* ``black``
|
||
* ``red``
|
||
* ``green``
|
||
* ``yellow``
|
||
* ``blue``
|
||
* ``magenta``
|
||
* ``cyan``
|
||
* ``white``
|
||
|
||
Each of these colors can then be modified by using the following
|
||
display options:
|
||
|
||
* ``bold``
|
||
* ``underscore``
|
||
* ``blink``
|
||
* ``reverse``
|
||
* ``conceal``
|
||
|
||
A color specification follows one of the following patterns:
|
||
|
||
* ``role=fg``
|
||
* ``role=fg/bg``
|
||
* ``role=fg,option,option``
|
||
* ``role=fg/bg,option,option``
|
||
|
||
where ``role`` is the name of a valid color role, ``fg`` is the
|
||
foreground color, ``bg`` is the background color and each ``option``
|
||
is one of the color modifying options. Multiple color specifications
|
||
are then separated by a semicolon. For example::
|
||
|
||
export DJANGO_COLORS="error=yellow/blue,blink;notice=magenta"
|
||
|
||
would specify that errors be displayed using blinking yellow on blue,
|
||
and notices displayed using magenta. All other color roles would be
|
||
left uncolored.
|
||
|
||
Colors can also be specified by extending a base palette. If you put
|
||
a palette name in a color specification, all the colors implied by that
|
||
palette will be loaded. So::
|
||
|
||
export DJANGO_COLORS="light;error=yellow/blue,blink;notice=magenta"
|
||
|
||
would specify the use of all the colors in the light color palette,
|
||
*except* for the colors for errors and notices which would be
|
||
overridden as specified.
|
||
|
||
.. _ANSICON: http://adoxa.altervista.org/ansicon/
|
||
|
||
Bash completion
|
||
---------------
|
||
|
||
If you use the Bash shell, consider installing the Django bash completion
|
||
script, which lives in ``extras/django_bash_completion`` in the Django source
|
||
distribution. It enables tab-completion of ``django-admin`` and
|
||
``manage.py`` commands, so you can, for instance...
|
||
|
||
* Type ``django-admin``.
|
||
* Press [TAB] to see all available options.
|
||
* Type ``sql``, then [TAB], to see all available options whose names start
|
||
with ``sql``.
|
||
|
||
See :doc:`/howto/custom-management-commands` for how to add customized actions.
|
||
|
||
==========================================
|
||
Running management commands from your code
|
||
==========================================
|
||
|
||
.. function:: django.core.management.call_command(name, *args, **options)
|
||
|
||
To call a management command from code use ``call_command``.
|
||
|
||
``name``
|
||
the name of the command to call or a command object. Passing the name is
|
||
preferred unless the object is required for testing.
|
||
|
||
``*args``
|
||
a list of arguments accepted by the command. Arguments are passed to the
|
||
argument parser, so you can use the same style as you would on the command
|
||
line. For example, ``call_command('flush', '--verbosity=0')``.
|
||
|
||
``**options``
|
||
named options accepted on the command-line. Options are passed to the command
|
||
without triggering the argument parser, which means you'll need to pass the
|
||
correct type. For example, ``call_command('flush', verbosity=0)`` (zero must
|
||
be an integer rather than a string).
|
||
|
||
Examples::
|
||
|
||
from django.core import management
|
||
from django.core.management.commands import loaddata
|
||
|
||
management.call_command('flush', verbosity=0, interactive=False)
|
||
management.call_command('loaddata', 'test_data', verbosity=0)
|
||
management.call_command(loaddata.Command(), 'test_data', verbosity=0)
|
||
|
||
Note that command options that take no arguments are passed as keywords
|
||
with ``True`` or ``False``, as you can see with the ``interactive`` option above.
|
||
|
||
Named arguments can be passed by using either one of the following syntaxes::
|
||
|
||
# Similar to the command line
|
||
management.call_command('dumpdata', '--natural-foreign')
|
||
|
||
# Named argument similar to the command line minus the initial dashes and
|
||
# with internal dashes replaced by underscores
|
||
management.call_command('dumpdata', natural_foreign=True)
|
||
|
||
# `use_natural_foreign_keys` is the option destination variable
|
||
management.call_command('dumpdata', use_natural_foreign_keys=True)
|
||
|
||
Some command options have different names when using ``call_command()`` instead
|
||
of ``django-admin`` or ``manage.py``. For example, ``django-admin
|
||
createsuperuser --no-input`` translates to ``call_command('createsuperuser',
|
||
interactive=False)``. To find what keyword argument name to use for
|
||
``call_command()``, check the command's source code for the ``dest`` argument
|
||
passed to ``parser.add_argument()``.
|
||
|
||
Command options which take multiple options are passed a list::
|
||
|
||
management.call_command('dumpdata', exclude=['contenttypes', 'auth'])
|
||
|
||
The return value of the ``call_command()`` function is the same as the return
|
||
value of the ``handle()`` method of the command.
|
||
|
||
Output redirection
|
||
==================
|
||
|
||
Note that you can redirect standard output and error streams as all commands
|
||
support the ``stdout`` and ``stderr`` options. For example, you could write::
|
||
|
||
with open('/path/to/command_output', 'w') as f:
|
||
management.call_command('dumpdata', stdout=f)
|