mirror of
https://github.com/django/django.git
synced 2024-12-23 17:46:27 +00:00
1772 lines
58 KiB
Plaintext
1772 lines
58 KiB
Plaintext
=============================
|
||
django-admin.py and manage.py
|
||
=============================
|
||
|
||
``django-admin.py`` 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.
|
||
``manage.py`` is a thin wrapper around ``django-admin.py`` that takes care of
|
||
two things for you before delegating to ``django-admin.py``:
|
||
|
||
* It puts your project's package on ``sys.path``.
|
||
|
||
* It sets the :envvar:`DJANGO_SETTINGS_MODULE` environment variable so that
|
||
it points to your project's ``settings.py`` file.
|
||
|
||
* It calls :func:`django.setup()` to initialize various internals of Django.
|
||
|
||
.. versionadded:: 1.7
|
||
|
||
:func:`django.setup()` didn't exist in previous versions of Django.
|
||
|
||
The ``django-admin.py`` script should be on your system path if you installed
|
||
Django via its ``setup.py`` utility. If it's not on your path, you can find it
|
||
in ``site-packages/django/bin`` within your Python installation. Consider
|
||
symlinking it from some place on your path, such as ``/usr/local/bin``.
|
||
|
||
For Windows users, who do not have symlinking functionality available, you can
|
||
copy ``django-admin.py`` to a location on your existing path or edit the
|
||
``PATH`` settings (under ``Settings - Control Panel - System - Advanced -
|
||
Environment...``) to point to its installed location.
|
||
|
||
Generally, when working on a single Django project, it's easier to use
|
||
``manage.py`` than ``django-admin.py``. If you need to switch between multiple
|
||
Django settings files, use ``django-admin.py`` with
|
||
:envvar:`DJANGO_SETTINGS_MODULE` or the :djadminopt:`--settings` command line
|
||
option.
|
||
|
||
The command-line examples throughout this document use ``django-admin.py`` to
|
||
be consistent, but any example can use ``manage.py`` just as well.
|
||
|
||
Usage
|
||
=====
|
||
|
||
.. code-block:: bash
|
||
|
||
$ django-admin.py <command> [options]
|
||
$ manage.py <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.py help`` to display usage information and a list of the
|
||
commands provided by each application.
|
||
|
||
Run ``django-admin.py help --commands`` to display a list of all available
|
||
commands.
|
||
|
||
Run ``django-admin.py 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.py version`` to display the current Django version.
|
||
|
||
The output follows the schema described in :pep:`386`::
|
||
|
||
1.4.dev17026
|
||
1.4a1
|
||
1.4
|
||
|
||
Displaying debug output
|
||
-----------------------
|
||
|
||
Use :djadminopt:`--verbosity` to specify the amount of notification and debug information
|
||
that ``django-admin.py`` should print to the console. For more details, see the
|
||
documentation for the :djadminopt:`--verbosity` option.
|
||
|
||
Available commands
|
||
==================
|
||
|
||
check <appname appname ...>
|
||
---------------------------
|
||
|
||
.. django-admin:: check
|
||
|
||
.. versionchanged:: 1.7
|
||
|
||
Uses the :doc:`system check framework </ref/checks>` to inspect
|
||
the entire Django project for common problems.
|
||
|
||
The system check framework will confirm that there aren't any problems with
|
||
your installed models or your admin registrations. It will also provide warnings
|
||
of common compatibility problems introduced by upgrading Django to a new version.
|
||
Custom checks may be introduced by other libraries and applications.
|
||
|
||
By default, all apps will be checked. You can check a subset of apps by providing
|
||
a list of app labels as arguments::
|
||
|
||
python manage.py check auth admin myapp
|
||
|
||
If you do not specify any app, all apps will be checked.
|
||
|
||
.. django-admin-option:: --tag <tagname>
|
||
|
||
The :doc:`system check framework </ref/checks>` performs many different
|
||
types of checks. These check types are categorized with tags. You can use these tags
|
||
to restrict the checks performed to just those in a particular category. For example,
|
||
to perform only security and compatibility checks, you would run::
|
||
|
||
python manage.py check --tag security --tag compatibility
|
||
|
||
.. django-admin-option:: --list-tags
|
||
|
||
List all available tags.
|
||
|
||
compilemessages
|
||
---------------
|
||
|
||
.. django-admin:: compilemessages
|
||
|
||
Compiles .po files created by :djadmin:`makemessages` to .mo files for use with
|
||
the builtin gettext support. See :doc:`/topics/i18n/index`.
|
||
|
||
Use the :djadminopt:`--locale` option (or its shorter version ``-l``) to
|
||
specify the locale(s) to process. If not provided, all locales are processed.
|
||
|
||
.. versionadded:: 1.8
|
||
|
||
Use the :djadminopt:`--exclude` option (or its shorter version ``-x``) to
|
||
specify the locale(s) to exclude from processing. If not provided, no locales
|
||
are excluded.
|
||
|
||
Example usage::
|
||
|
||
django-admin.py compilemessages --locale=pt_BR
|
||
django-admin.py compilemessages --locale=pt_BR --locale=fr
|
||
django-admin.py compilemessages -l pt_BR
|
||
django-admin.py compilemessages -l pt_BR -l fr
|
||
django-admin.py compilemessages --exclude=pt_BR
|
||
django-admin.py compilemessages --exclude=pt_BR --exclude=fr
|
||
django-admin.py compilemessages -x pt_BR
|
||
django-admin.py compilemessages -x pt_BR -x fr
|
||
|
||
createcachetable
|
||
----------------
|
||
|
||
.. django-admin:: createcachetable
|
||
|
||
Creates the cache tables for use with the database cache backend. See
|
||
:doc:`/topics/cache` for more information.
|
||
|
||
The :djadminopt:`--database` option can be used to specify the database
|
||
onto which the cachetable will be installed.
|
||
|
||
.. versionchanged:: 1.7
|
||
|
||
It is no longer necessary to provide the cache table name or the
|
||
:djadminopt:`--database` option. Django takes this information from your
|
||
settings file. If you have configured multiple caches or multiple databases,
|
||
all cache tables are created.
|
||
|
||
dbshell
|
||
-------
|
||
|
||
.. django-admin:: dbshell
|
||
|
||
Runs the command-line client for the database engine specified in your
|
||
``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.
|
||
|
||
This command assumes the programs are on your ``PATH`` so that a simple call to
|
||
the program name (``psql``, ``mysql``, ``sqlite3``) will find the program in
|
||
the right place. There's no way to specify the location of the program
|
||
manually.
|
||
|
||
The :djadminopt:`--database` option can be used to specify the database
|
||
onto which to open a shell.
|
||
|
||
diffsettings
|
||
------------
|
||
|
||
.. django-admin:: diffsettings
|
||
|
||
Displays differences between the current settings file and Django's default
|
||
settings.
|
||
|
||
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``.
|
||
|
||
The :djadminopt:`--all` option may be provided to display all settings, even
|
||
if they have Django's default value. Such settings are prefixed by ``"###"``.
|
||
|
||
dumpdata <app_label app_label app_label.Model ...>
|
||
--------------------------------------------------
|
||
|
||
.. django-admin:: dumpdata
|
||
|
||
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.
|
||
|
||
The :djadminopt:`--all` option may be provided to specify that
|
||
``dumpdata`` should use Django's base manager, dumping records which
|
||
might otherwise be filtered or modified by a custom manager.
|
||
|
||
.. django-admin-option:: --format <fmt>
|
||
|
||
By default, ``dumpdata`` will format its output in JSON, but you can use the
|
||
``--format`` option to specify another format. Currently supported formats
|
||
are listed in :ref:`serialization-formats`.
|
||
|
||
.. django-admin-option:: --indent <num>
|
||
|
||
By default, ``dumpdata`` will output all data on a single line. This isn't
|
||
easy for humans to read, so you can use the ``--indent`` option to
|
||
pretty-print the output with a number of indentation spaces.
|
||
|
||
The :djadminopt:`--exclude` option may be provided to prevent specific
|
||
applications or models (specified as in the form of ``app_label.ModelName``)
|
||
from being dumped. If you specify a model name to ``dumpdata``, the dumped
|
||
output will be restricted to that model, rather than the entire application.
|
||
You can also mix application names and model names.
|
||
|
||
The :djadminopt:`--database` option can be used to specify the database
|
||
from which data will be dumped.
|
||
|
||
.. django-admin-option:: --natural-foreign
|
||
|
||
.. versionadded:: 1.7
|
||
|
||
When this option is specified, Django will use 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 are dumping ``contrib.auth``
|
||
``Permission`` objects or ``contrib.contenttypes`` ``ContentType`` objects, you
|
||
should probably be using 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
|
||
|
||
.. versionadded:: 1.7
|
||
|
||
When this option is specified, Django will not provide the primary key in the
|
||
serialized data of this object since it can be calculated during
|
||
deserialization.
|
||
|
||
.. django-admin-option:: --natural
|
||
|
||
.. deprecated:: 1.7
|
||
Equivalent to the :djadminopt:`--natural-foreign` option; use that instead.
|
||
|
||
Use :ref:`natural keys <topics-serialization-natural-keys>` to represent
|
||
any foreign key and many-to-many relationship with a model that provides
|
||
a natural key definition.
|
||
|
||
.. django-admin-option:: --pks
|
||
|
||
By default, ``dumpdata`` will output all the records of the model, but
|
||
you can use the ``--pks`` option to specify a comma separated list of
|
||
primary keys on which to filter. This is only available when dumping
|
||
one model.
|
||
|
||
.. django-admin-option:: --output
|
||
|
||
.. versionadded:: 1.8
|
||
|
||
By default ``dumpdata`` will output all the serialized data to standard output.
|
||
This options allows to specify the file to which the data is to be written.
|
||
|
||
flush
|
||
-----
|
||
|
||
.. django-admin:: flush
|
||
|
||
Removes all data from the database, re-executes any post-synchronization
|
||
handlers, and reinstalls any initial data fixtures.
|
||
|
||
The :djadminopt:`--noinput` option may be provided to suppress all user
|
||
prompts.
|
||
|
||
The :djadminopt:`--database` option may be used to specify the database
|
||
to flush.
|
||
|
||
``--no-initial-data``
|
||
~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Use ``--no-initial-data`` to avoid loading the initial_data fixture.
|
||
|
||
|
||
inspectdb
|
||
---------
|
||
|
||
.. django-admin:: inspectdb
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
* 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.
|
||
|
||
Primary keys are automatically introspected for PostgreSQL, MySQL and
|
||
SQLite, in which case Django puts in the ``primary_key=True`` where
|
||
needed.
|
||
|
||
``inspectdb`` works with PostgreSQL, MySQL and SQLite. Foreign-key detection
|
||
only works in PostgreSQL and with certain types of MySQL tables.
|
||
|
||
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 simply remove
|
||
it because ``True`` is its default value).
|
||
|
||
The :djadminopt:`--database` option may be used to specify the
|
||
database to introspect.
|
||
|
||
loaddata <fixture fixture ...>
|
||
------------------------------
|
||
|
||
.. django-admin:: loaddata
|
||
|
||
Searches for and loads the contents of the named fixture into the database.
|
||
|
||
The :djadminopt:`--database` option can be used to specify the database
|
||
onto which the data will be loaded.
|
||
|
||
.. django-admin-option:: --ignorenonexistent
|
||
|
||
The :djadminopt:`--ignorenonexistent` option can be used to ignore fields and
|
||
models that may have been removed since the fixture was originally generated.
|
||
|
||
.. versionchanged:: 1.7
|
||
|
||
``--app`` was added.
|
||
|
||
.. versionchanged:: 1.8
|
||
|
||
``--ignorenonexistent`` also ignores non-existent models.
|
||
|
||
.. django-admin-option:: --app
|
||
|
||
The :djadminopt:`--app` option can be used to specify a single app to look
|
||
for fixtures in rather than looking through all apps.
|
||
|
||
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.py 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.py 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.py 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 simple 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``, or ``bz2`` format. For example::
|
||
|
||
django-admin.py loaddata mydata.json
|
||
|
||
would look for any of ``mydata.json``, ``mydata.json.zip``,
|
||
``mydata.json.gz``, or ``mydata.json.bz2``. The first file contained within a
|
||
zip-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.
|
||
|
||
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 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.
|
||
|
||
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.
|
||
|
||
.. django-admin-option:: --all
|
||
|
||
Use the ``--all`` or ``-a`` option to update the message files for all
|
||
available languages.
|
||
|
||
Example usage::
|
||
|
||
django-admin.py makemessages --all
|
||
|
||
.. django-admin-option:: --extension
|
||
|
||
Use the ``--extension`` or ``-e`` option to specify a list of file extensions
|
||
to examine (default: ".html", ".txt").
|
||
|
||
Example usage::
|
||
|
||
django-admin.py makemessages --locale=de --extension xhtml
|
||
|
||
Separate multiple extensions with commas or use -e or --extension multiple times::
|
||
|
||
django-admin.py makemessages --locale=de --extension=html,txt --extension xml
|
||
|
||
Use the :djadminopt:`--locale` option (or its shorter version ``-l``) to
|
||
specify the locale(s) to process.
|
||
|
||
.. versionadded:: 1.8
|
||
|
||
Use the :djadminopt:`--exclude` option (or its shorter version ``-x``) to
|
||
specify the locale(s) to exclude from processing. If not provided, no locales
|
||
are excluded.
|
||
|
||
Example usage::
|
||
|
||
django-admin.py makemessages --locale=pt_BR
|
||
django-admin.py makemessages --locale=pt_BR --locale=fr
|
||
django-admin.py makemessages -l pt_BR
|
||
django-admin.py makemessages -l pt_BR -l fr
|
||
django-admin.py makemessages --exclude=pt_BR
|
||
django-admin.py makemessages --exclude=pt_BR --exclude=fr
|
||
django-admin.py makemessages -x pt_BR
|
||
django-admin.py makemessages -x pt_BR -x fr
|
||
|
||
|
||
.. versionchanged:: 1.7
|
||
|
||
Added the ``--previous`` option to the ``msgmerge`` command when merging
|
||
with existing po files.
|
||
|
||
.. django-admin-option:: --domain
|
||
|
||
Use the ``--domain`` or ``-d`` option to change the domain of the messages files.
|
||
Currently supported:
|
||
|
||
* ``django`` for all ``*.py``, ``*.html`` and ``*.txt`` files (default)
|
||
* ``djangojs`` for ``*.js`` files
|
||
|
||
.. django-admin-option:: --symlinks
|
||
|
||
Use the ``--symlinks`` or ``-s`` option to follow symlinks to directories when
|
||
looking for new translation strings.
|
||
|
||
Example usage::
|
||
|
||
django-admin.py makemessages --locale=de --symlinks
|
||
|
||
.. django-admin-option:: --ignore
|
||
|
||
Use the ``--ignore`` or ``-i`` option to ignore 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.py makemessages --locale=en_US --ignore=apps/* --ignore=secret/*.html
|
||
|
||
.. django-admin-option:: --no-default-ignore
|
||
|
||
Use the ``--no-default-ignore`` option to disable the default values of
|
||
:djadminopt:`--ignore`.
|
||
|
||
.. django-admin-option:: --no-wrap
|
||
|
||
Use the ``--no-wrap`` option to disable breaking long message lines into
|
||
several lines in language files.
|
||
|
||
.. django-admin-option:: --no-location
|
||
|
||
Use the ``--no-location`` option to not write '``#: filename:line``’
|
||
comment lines in language files. Note that using this option makes it harder
|
||
for technically skilled translators to understand each message's context.
|
||
|
||
.. django-admin-option:: --keep-pot
|
||
|
||
Use the ``--keep-pot`` option to prevent Django from deleting the temporary
|
||
.pot files it generates before creating the .po file. This is useful for
|
||
debugging errors which may prevent the final language files from being created.
|
||
|
||
makemigrations [<app_label>]
|
||
----------------------------
|
||
|
||
.. django-admin:: makemigrations
|
||
|
||
.. versionadded:: 1.7
|
||
|
||
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).
|
||
|
||
.. django-admin-option:: --empty
|
||
|
||
The ``--empty`` option will cause ``makemigrations`` to output an empty
|
||
migration for the specified apps, for manual editing. This option is only
|
||
for advanced users and should not be used unless you are familiar with
|
||
the migration format, migration operations, and the dependencies between
|
||
your migrations.
|
||
|
||
migrate [<app_label> [<migrationname>]]
|
||
---------------------------------------
|
||
|
||
.. django-admin:: migrate
|
||
|
||
.. versionadded:: 1.7
|
||
|
||
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 migrated apps have all of their migrations run,
|
||
and all unmigrated apps are synchronized with the database,
|
||
* ``<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 it
|
||
would have just run the given migration, but no further - this may involve
|
||
unapplying migrations if you have previously migrated past the named
|
||
migration. Use the name `zero` to unapply all migrations for an app.
|
||
|
||
runfcgi [options]
|
||
-----------------
|
||
|
||
.. django-admin:: runfcgi
|
||
|
||
.. deprecated:: 1.7
|
||
FastCGI support is deprecated and will be removed in Django 1.9.
|
||
|
||
Starts a set of FastCGI processes suitable for use with any Web server that
|
||
supports the FastCGI protocol. See the :doc:`FastCGI deployment documentation
|
||
</howto/deployment/fastcgi>` for details. Requires the Python FastCGI module from
|
||
`flup`_.
|
||
|
||
Internally, this wraps the WSGI application object specified by the
|
||
:setting:`WSGI_APPLICATION` setting.
|
||
|
||
.. _flup: http://www.saddi.com/software/flup/
|
||
|
||
The options accepted by this command are passed to the FastCGI library and
|
||
don't use the ``'--'`` prefix as is usual for other Django management commands.
|
||
|
||
.. django-admin-option:: protocol
|
||
|
||
``protocol=PROTOCOL``
|
||
|
||
Protocol to use. *PROTOCOL* can be ``fcgi``, ``scgi``, ``ajp``, etc.
|
||
(default is ``fcgi``)
|
||
|
||
.. django-admin-option:: host
|
||
|
||
``host=HOSTNAME``
|
||
|
||
Hostname to listen on.
|
||
|
||
.. django-admin-option:: port
|
||
|
||
``port=PORTNUM``
|
||
|
||
Port to listen on.
|
||
|
||
.. django-admin-option:: socket
|
||
|
||
``socket=FILE``
|
||
|
||
UNIX socket to listen on.
|
||
|
||
.. django-admin-option:: method
|
||
|
||
``method=IMPL``
|
||
|
||
Possible values: ``prefork`` or ``threaded`` (default ``prefork``)
|
||
|
||
.. django-admin-option:: maxrequests
|
||
|
||
``maxrequests=NUMBER``
|
||
|
||
Number of requests a child handles before it is killed and a new child is
|
||
forked (0 means no limit).
|
||
|
||
.. django-admin-option:: maxspare
|
||
|
||
``maxspare=NUMBER``
|
||
|
||
Max number of spare processes / threads.
|
||
|
||
.. django-admin-option:: minspare
|
||
|
||
``minspare=NUMBER``
|
||
|
||
Min number of spare processes / threads.
|
||
|
||
.. django-admin-option:: maxchildren
|
||
|
||
``maxchildren=NUMBER``
|
||
|
||
Hard limit number of processes / threads.
|
||
|
||
.. django-admin-option:: daemonize
|
||
|
||
``daemonize=BOOL``
|
||
|
||
Whether to detach from terminal.
|
||
|
||
.. django-admin-option:: pidfile
|
||
|
||
``pidfile=FILE``
|
||
|
||
Write the spawned process-id to file *FILE*.
|
||
|
||
.. django-admin-option:: workdir
|
||
|
||
``workdir=DIRECTORY``
|
||
|
||
Change to directory *DIRECTORY* when daemonizing.
|
||
|
||
.. django-admin-option:: debug
|
||
|
||
``debug=BOOL``
|
||
|
||
Set to true to enable flup tracebacks.
|
||
|
||
.. django-admin-option:: outlog
|
||
|
||
``outlog=FILE``
|
||
|
||
Write stdout to the *FILE* file.
|
||
|
||
.. django-admin-option:: errlog
|
||
|
||
``errlog=FILE``
|
||
|
||
Write stderr to the *FILE* file.
|
||
|
||
.. django-admin-option:: umask
|
||
|
||
``umask=UMASK``
|
||
|
||
Umask to use when daemonizing. The value is interpreted as an octal number
|
||
(default value is ``022``).
|
||
|
||
Example usage::
|
||
|
||
django-admin.py runfcgi socket=/tmp/fcgi.sock method=prefork daemonize=true \
|
||
pidfile=/var/run/django-fcgi.pid
|
||
|
||
Run a FastCGI server as a daemon and write the spawned PID in a file.
|
||
|
||
runserver [port or address:port]
|
||
--------------------------------
|
||
|
||
.. django-admin:: runserver
|
||
|
||
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.
|
||
|
||
.. versionchanged:: 1.7
|
||
|
||
Compiling translation files now also restarts the development server.
|
||
|
||
If you are using Linux and install `pyinotify`_, kernel signals will be used to
|
||
autoreload the server (rather than polling file modification timestamps each
|
||
second). This offers better scaling to large projects, reduction in response
|
||
time to code modification, more robust change detection, and battery usage
|
||
reduction.
|
||
|
||
.. _pyinotify: https://pypi.python.org/pypi/pyinotify/
|
||
|
||
.. versionadded:: 1.7
|
||
|
||
``pyinotify`` support was added.
|
||
|
||
When you start the server, and each time you change Python code while the
|
||
server is running, the server will check your entire Django project for errors (see
|
||
the :djadmin:`check` command). If any errors are found, they will be printed
|
||
to standard output, but it won't stop the server.
|
||
|
||
You can run as many servers as you want, as long as they're on separate ports.
|
||
Just execute ``django-admin.py 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.
|
||
|
||
.. django-admin-option:: --noreload
|
||
|
||
Use the ``--noreload`` option to disable the use of 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.
|
||
|
||
Example usage::
|
||
|
||
django-admin.py runserver --noreload
|
||
|
||
.. django-admin-option:: --nothreading
|
||
|
||
The development server is multithreaded by default. Use the ``--nothreading``
|
||
option to disable the use of threading in the development server.
|
||
|
||
.. django-admin-option:: --ipv6, -6
|
||
|
||
Use the ``--ipv6`` (or shorter ``-6``) option to tell Django to use IPv6 for
|
||
the development server. This changes the default IP address from
|
||
``127.0.0.1`` to ``::1``.
|
||
|
||
Example usage::
|
||
|
||
django-admin.py runserver --ipv6
|
||
|
||
Examples of using different ports and addresses
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Port 8000 on IP address ``127.0.0.1``::
|
||
|
||
django-admin.py runserver
|
||
|
||
Port 8000 on IP address ``1.2.3.4``::
|
||
|
||
django-admin.py runserver 1.2.3.4:8000
|
||
|
||
Port 7000 on IP address ``127.0.0.1``::
|
||
|
||
django-admin.py runserver 7000
|
||
|
||
Port 7000 on IP address ``1.2.3.4``::
|
||
|
||
django-admin.py runserver 1.2.3.4:7000
|
||
|
||
Port 8000 on IPv6 address ``::1``::
|
||
|
||
django-admin.py runserver -6
|
||
|
||
Port 7000 on IPv6 address ``::1``::
|
||
|
||
django-admin.py runserver -6 7000
|
||
|
||
Port 7000 on IPv6 address ``2001:0db8:1234:5678::9``::
|
||
|
||
django-admin.py runserver [2001:0db8:1234:5678::9]:7000
|
||
|
||
Port 8000 on IPv4 address of host ``localhost``::
|
||
|
||
django-admin.py runserver localhost:8000
|
||
|
||
Port 8000 on IPv6 address of host ``localhost``::
|
||
|
||
django-admin.py 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`.
|
||
|
||
shell
|
||
-----
|
||
|
||
.. django-admin:: shell
|
||
|
||
Starts the Python interactive interpreter.
|
||
|
||
Django will use IPython_ or bpython_ if either is installed. If you have a
|
||
rich shell installed but want to force use of the "plain" Python interpreter,
|
||
use the ``--plain`` option, like so::
|
||
|
||
django-admin.py shell --plain
|
||
|
||
If you would like to specify either IPython or bpython as your interpreter if
|
||
you have both installed you can specify an alternative interpreter interface
|
||
with the ``-i`` or ``--interface`` options like so:
|
||
|
||
IPython::
|
||
|
||
django-admin.py shell -i ipython
|
||
django-admin.py shell --interface ipython
|
||
|
||
|
||
bpython::
|
||
|
||
django-admin.py shell -i bpython
|
||
django-admin.py shell --interface bpython
|
||
|
||
|
||
.. _IPython: http://ipython.scipy.org/
|
||
.. _bpython: http://bpython-interpreter.org/
|
||
|
||
When the "plain" Python interactive interpreter starts (be it because
|
||
``--plain`` was specified or because no other interactive interface is
|
||
available) it reads the script pointed to by the :envvar:`PYTHONSTARTUP`
|
||
environment variable and the ``~/.pythonrc.py`` script. If you don't wish this
|
||
behavior you can use the ``--no-startup`` option. e.g.::
|
||
|
||
django-admin.py shell --plain --no-startup
|
||
|
||
sql <app_label app_label ...>
|
||
-----------------------------
|
||
|
||
.. django-admin:: sql
|
||
|
||
Prints the CREATE TABLE SQL statements for the given app name(s).
|
||
|
||
The :djadminopt:`--database` option can be used to specify the database for
|
||
which to print the SQL.
|
||
|
||
sqlall <app_label app_label ...>
|
||
--------------------------------
|
||
|
||
.. django-admin:: sqlall
|
||
|
||
Prints the CREATE TABLE and initial-data SQL statements for the given app name(s).
|
||
|
||
Refer to the description of :djadmin:`sqlcustom` for an explanation of how to
|
||
specify initial data.
|
||
|
||
The :djadminopt:`--database` option can be used to specify the database for
|
||
which to print the SQL.
|
||
|
||
sqlclear <app_label app_label ...>
|
||
----------------------------------
|
||
|
||
.. django-admin:: sqlclear
|
||
|
||
Prints the DROP TABLE SQL statements for the given app name(s).
|
||
|
||
The :djadminopt:`--database` option can be used to specify the database for
|
||
which to print the SQL.
|
||
|
||
sqlcustom <app_label app_label ...>
|
||
-----------------------------------
|
||
|
||
.. django-admin:: sqlcustom
|
||
|
||
Prints the custom SQL statements for the given app name(s).
|
||
|
||
For each model in each specified app, this command looks for the file
|
||
``<app_label>/sql/<modelname>.sql``, where ``<app_label>`` is the given app
|
||
name and ``<modelname>`` is the model's name in lowercase. For example, if you
|
||
have an app ``news`` that includes a ``Story`` model, ``sqlcustom`` will
|
||
attempt to read a file ``news/sql/story.sql`` and append it to the output of
|
||
this command.
|
||
|
||
Each of the SQL files, if given, is expected to contain valid SQL. The SQL
|
||
files are piped directly into the database after all of the models'
|
||
table-creation statements have been executed. Use this SQL hook to make any
|
||
table modifications, or insert any SQL functions into the database.
|
||
|
||
Note that the order in which the SQL files are processed is undefined.
|
||
|
||
The :djadminopt:`--database` option can be used to specify the database for
|
||
which to print the SQL.
|
||
|
||
sqldropindexes <app_label app_label ...>
|
||
----------------------------------------
|
||
|
||
.. django-admin:: sqldropindexes
|
||
|
||
Prints the DROP INDEX SQL statements for the given app name(s).
|
||
|
||
The :djadminopt:`--database` option can be used to specify the database for
|
||
which to print the SQL.
|
||
|
||
sqlflush
|
||
--------
|
||
|
||
.. django-admin:: sqlflush
|
||
|
||
Prints the SQL statements that would be executed for the :djadmin:`flush`
|
||
command.
|
||
|
||
The :djadminopt:`--database` option can be used to specify the database for
|
||
which to print the SQL.
|
||
|
||
sqlindexes <app_label app_label ...>
|
||
------------------------------------
|
||
|
||
.. django-admin:: sqlindexes
|
||
|
||
Prints the CREATE INDEX SQL statements for the given app name(s).
|
||
|
||
The :djadminopt:`--database` option can be used to specify the database for
|
||
which to print the SQL.
|
||
|
||
sqlmigrate <app_label> <migrationname>
|
||
--------------------------------------
|
||
|
||
.. django-admin:: sqlmigrate
|
||
|
||
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.
|
||
|
||
The :djadminopt:`--database` option can be used to specify the database for
|
||
which to generate the SQL.
|
||
|
||
.. django-admin-option:: --backwards
|
||
|
||
By default, the SQL created is for running the migration in the forwards
|
||
direction. Pass ``--backwards`` to generate the SQL for
|
||
unapplying the migration instead.
|
||
|
||
sqlsequencereset <app_label app_label ...>
|
||
------------------------------------------
|
||
|
||
.. django-admin:: sqlsequencereset
|
||
|
||
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.
|
||
|
||
The :djadminopt:`--database` option can be used to specify the database for
|
||
which to print the SQL.
|
||
|
||
squashmigrations <app_label> <migration_name>
|
||
---------------------------------------------
|
||
|
||
.. django-admin:: squashmigrations
|
||
|
||
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`.
|
||
|
||
.. django-admin-option:: --no-optimize
|
||
|
||
By default, Django will try to optimize the operations in your migrations
|
||
to reduce the size of the resulting file. Pass ``--no-optimize`` if this
|
||
process is failing for you or creating incorrect migrations, though please
|
||
also file a Django bug report about the behavior, as optimization is meant
|
||
to be safe.
|
||
|
||
|
||
startapp <app_label> [destination]
|
||
----------------------------------
|
||
|
||
.. django-admin:: startapp
|
||
|
||
Creates a Django app directory structure for the given app name in the current
|
||
directory or the given destination.
|
||
|
||
By default the directory created contains a ``models.py`` file and other app
|
||
template files. (See the `source`_ for more details.) 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.py startapp myapp /Users/jezdez/Code/myapp
|
||
|
||
.. _custom-app-and-project-templates:
|
||
|
||
.. django-admin-option:: --template
|
||
|
||
With the ``--template`` option, you can use a custom app template by providing
|
||
either the path to a directory with the app template file, or a path to a
|
||
compressed file (``.tar.gz``, ``.tar.bz2``, ``.tgz``, ``.tbz``, ``.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.py 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.py startapp --template=https://github.com/githubuser/django-app-template/archive/master.zip myapp
|
||
|
||
When Django copies the app template files, it also renders certain files
|
||
through the template engine: the files whose extensions match the
|
||
``--extension`` option (``py`` by default) and the files whose names are passed
|
||
with the ``--name`` option. The :class:`template context
|
||
<django.template.Context>` used 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
|
||
- ``docs_version`` -- the version of the documentation: ``'dev'`` or ``'1.x'``
|
||
|
||
.. _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`
|
||
templatetag to "escape" the various parts of the template syntax.
|
||
|
||
.. _source: https://github.com/django/django/tree/master/django/conf/app_template/
|
||
|
||
startproject <projectname> [destination]
|
||
----------------------------------------
|
||
|
||
.. django-admin:: startproject
|
||
|
||
Creates a Django project directory structure for the given project name in
|
||
the current directory or the given destination.
|
||
|
||
By default, the new directory contains ``manage.py`` and a project package
|
||
(containing a ``settings.py`` and other files). See the `template source`_ for
|
||
details.
|
||
|
||
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.py startproject myproject /Users/jezdez/Code/myproject_repo
|
||
|
||
As with the :djadmin:`startapp` command, the ``--template`` option lets you
|
||
specify a directory, file path or URL of a custom project template. See the
|
||
:djadmin:`startapp` documentation for details of supported project template
|
||
formats.
|
||
|
||
For example, this would look for a project template in the given directory
|
||
when creating the ``myproject`` project::
|
||
|
||
django-admin.py startproject --template=/Users/jezdez/Code/my_project_template myproject
|
||
|
||
Django will also accept URLs (``http``, ``https``, ``ftp``) to compressed
|
||
archives with the project 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.py startproject --template=https://github.com/githubuser/django-project-template/archive/master.zip myproject
|
||
|
||
When Django copies the project template files, it also renders certain files
|
||
through the template engine: the files whose extensions match the
|
||
``--extension`` option (``py`` by default) and the files whose names are passed
|
||
with the ``--name`` option. 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'``
|
||
|
||
Please also see the :ref:`rendering warning <render_warning>` as mentioned
|
||
for :djadmin:`startapp`.
|
||
|
||
.. _`template source`: https://github.com/django/django/tree/master/django/conf/project_template/
|
||
|
||
syncdb
|
||
------
|
||
|
||
.. django-admin:: syncdb
|
||
|
||
.. deprecated:: 1.7
|
||
|
||
This command has been deprecated in favor of the :djadmin:`migrate`
|
||
command, which performs both the old behavior as well as executing
|
||
migrations. It is now just an alias to that command.
|
||
|
||
Alias for :djadmin:`migrate`.
|
||
|
||
test <app or test identifier>
|
||
-----------------------------
|
||
|
||
.. django-admin:: test
|
||
|
||
Runs tests for all installed models. See :doc:`/topics/testing/index` for more
|
||
information.
|
||
|
||
.. django-admin-option:: --failfast
|
||
|
||
The ``--failfast`` option can be used to stop running tests and report the
|
||
failure immediately after a test fails.
|
||
|
||
.. django-admin-option:: --testrunner
|
||
|
||
The ``--testrunner`` option can be used to control the test runner class that
|
||
is used to execute tests. If this value is provided, it overrides the value
|
||
provided by the :setting:`TEST_RUNNER` setting.
|
||
|
||
.. django-admin-option:: --liveserver
|
||
|
||
The ``--liveserver`` option can be used to override the default address where
|
||
the live server (used with :class:`~django.test.LiveServerTestCase`) is
|
||
expected to run from. The default value is ``localhost:8081``.
|
||
|
||
testserver <fixture fixture ...>
|
||
--------------------------------
|
||
|
||
.. django-admin:: testserver
|
||
|
||
Runs a Django development server (as in :djadmin:`runserver`) using data from
|
||
the given fixture(s).
|
||
|
||
For example, this command::
|
||
|
||
django-admin.py testserver mydata.json
|
||
|
||
...would perform the following steps:
|
||
|
||
1. Create a test database, as described in :ref:`the-test-database`.
|
||
2. Populate the test database with fixture data from the given fixtures.
|
||
(For more on fixtures, see the documentation for :djadmin:`loaddata` above.)
|
||
3. 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 [port number or ipaddr:port]
|
||
|
||
Use ``--addrport`` to specify 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.py testserver --addrport 7000 fixture1 fixture2
|
||
django-admin.py 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.py testserver --addrport 1.2.3.4:7000 test
|
||
|
||
The :djadminopt:`--noinput` option may be provided to suppress all user
|
||
prompts.
|
||
|
||
validate
|
||
--------
|
||
|
||
.. django-admin:: validate
|
||
|
||
.. deprecated:: 1.7
|
||
Replaced by the :djadmin:`check` command.
|
||
|
||
Validates all installed models (according to the :setting:`INSTALLED_APPS`
|
||
setting) and prints validation errors to standard output.
|
||
|
||
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
|
||
|
||
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 twice the password of
|
||
the user given as parameter. If they both match, the new password will be
|
||
changed immediately. If you do not supply a user, the command will attempt to
|
||
change the password whose username matches the current user.
|
||
|
||
Use the ``--database`` option to specify the database to query for the user. If
|
||
it's not supplied, Django will use the ``default`` database.
|
||
|
||
Example usage::
|
||
|
||
django-admin.py changepassword ringo
|
||
|
||
createsuperuser
|
||
~~~~~~~~~~~~~~~
|
||
|
||
.. django-admin:: createsuperuser
|
||
|
||
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 but did not
|
||
do so during the first :djadmin:`migrate`, 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, 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.
|
||
|
||
.. django-admin-option:: --username
|
||
.. django-admin-option:: --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.
|
||
|
||
Use the ``--database`` option to specify the database into which the superuser
|
||
object will be saved.
|
||
|
||
``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
|
||
===============
|
||
|
||
Although some commands may allow their own custom options, every command
|
||
allows for the following options:
|
||
|
||
.. django-admin-option:: --pythonpath
|
||
|
||
Example usage::
|
||
|
||
django-admin.py migrate --pythonpath='/home/djangoprojects/myproject'
|
||
|
||
Adds the given filesystem path to the Python `import search path`_. If this
|
||
isn't provided, ``django-admin.py`` will use the ``PYTHONPATH`` environment
|
||
variable.
|
||
|
||
Note that this option is unnecessary in ``manage.py``, because it takes care of
|
||
setting the Python path for you.
|
||
|
||
.. _import search path: http://diveintopython.net/getting_to_know_python/everything_is_an_object.html
|
||
|
||
.. django-admin-option:: --settings
|
||
|
||
Example usage::
|
||
|
||
django-admin.py migrate --settings=mysite.settings
|
||
|
||
Explicitly 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.py`` will use the ``DJANGO_SETTINGS_MODULE`` environment
|
||
variable.
|
||
|
||
Note that this option is unnecessary in ``manage.py``, because it uses
|
||
``settings.py`` from the current project by default.
|
||
|
||
.. django-admin-option:: --traceback
|
||
|
||
Example usage::
|
||
|
||
django-admin.py migrate --traceback
|
||
|
||
By default, ``django-admin.py`` will show a simple error message whenever an
|
||
:class:`~django.core.management.CommandError` occurs, but a full stack trace
|
||
for any other exception. If you specify ``--traceback``, ``django-admin.py``
|
||
will also output a full stack trace when a ``CommandError`` is raised.
|
||
|
||
.. django-admin-option:: --verbosity
|
||
|
||
Example usage::
|
||
|
||
django-admin.py migrate --verbosity 2
|
||
|
||
Use ``--verbosity`` to specify the amount of notification and debug information
|
||
that ``django-admin.py`` should print to the console.
|
||
|
||
* ``0`` means no output.
|
||
* ``1`` means normal output (default).
|
||
* ``2`` means verbose output.
|
||
* ``3`` means *very* verbose output.
|
||
|
||
.. django-admin-option:: --no-color
|
||
|
||
.. versionadded:: 1.7
|
||
|
||
Example usage::
|
||
|
||
django-admin.py sqlall --no-color
|
||
|
||
By default, ``django-admin.py`` will format the output to be colorized. For
|
||
example, errors will be printed to the console in red and SQL statements will
|
||
be syntax highlighted. To prevent this and have a plain text output, pass the
|
||
``--no-color`` option when running your command.
|
||
|
||
Common options
|
||
==============
|
||
|
||
The following options are not available on every command, but they are common
|
||
to a number of commands.
|
||
|
||
.. django-admin-option:: --database
|
||
|
||
Used to specify the database on which a command will operate. If not
|
||
specified, this option will default to an alias of ``default``.
|
||
|
||
For example, to dump data from the database with the alias ``master``::
|
||
|
||
django-admin.py dumpdata --database=master
|
||
|
||
.. django-admin-option:: --exclude
|
||
|
||
Exclude a specific application from the applications whose contents is
|
||
output. For example, to specifically exclude the ``auth`` application from
|
||
the output of dumpdata, you would call::
|
||
|
||
django-admin.py dumpdata --exclude=auth
|
||
|
||
If you want to exclude multiple applications, use multiple ``--exclude``
|
||
directives::
|
||
|
||
django-admin.py dumpdata --exclude=auth --exclude=contenttypes
|
||
|
||
.. django-admin-option:: --locale
|
||
|
||
Use the ``--locale`` or ``-l`` option to specify the locale to process.
|
||
If not provided all locales are processed.
|
||
|
||
.. django-admin-option:: --noinput
|
||
|
||
Use the ``--noinput`` option to suppress all user prompting, such as "Are
|
||
you sure?" confirmation messages. This is useful if ``django-admin.py`` is
|
||
being executed as an unattended, automated script.
|
||
|
||
Extra niceties
|
||
==============
|
||
|
||
.. _syntax-coloring:
|
||
|
||
Syntax coloring
|
||
---------------
|
||
|
||
The ``django-admin.py`` / ``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.
|
||
|
||
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 ``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.
|
||
* ``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.
|
||
|
||
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 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.
|
||
|
||
.. versionadded:: 1.7
|
||
|
||
Support for color-coded output from ``django-admin.py`` / ``manage.py``
|
||
utilities on Windows by relying on the ANSICON application was added in Django
|
||
1.7.
|
||
|
||
.. _ANSICON: http://adoxa.hostmyway.net/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
|
||
distribution. It enables tab-completion of ``django-admin.py`` and
|
||
``manage.py`` commands, so you can, for instance...
|
||
|
||
* Type ``django-admin.py``.
|
||
* 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
|
||
==========================================
|
||
|
||
.. _call-command:
|
||
|
||
.. 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.
|
||
|
||
``*args``
|
||
a list of arguments accepted by the command.
|
||
|
||
``**options``
|
||
named options accepted on the command-line.
|
||
|
||
Examples::
|
||
|
||
from django.core import management
|
||
management.call_command('flush', verbosity=0, interactive=False)
|
||
management.call_command('loaddata', 'test_data', verbosity=0)
|
||
|
||
Note that command options that take no arguments are passed as keywords
|
||
with ``True`` or ``False``::
|
||
|
||
management.call_command('dumpdata', use_natural_keys=True)
|
||
|
||
Command options which take multiple options are passed a list::
|
||
|
||
management.call_command('dumpdata', exclude=['contenttypes', 'auth'])
|
||
|
||
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('/tmp/command_output') as f:
|
||
management.call_command('dumpdata', stdout=f)
|