=============================

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.

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``. Use ``django-admin.py`` with ``DJANGO_SETTINGS_MODULE``, or the

``--settings`` command line option, if you need to switch between multiple

Django settings files.

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-option:: --help

Run ``django-admin.py help`` 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 ``INSTALLED_APPS``

contains the string ``'mysite.blog'``, the app name is ``blog``.

Determining the version

-----------------------

.. django-admin-option:: --version

Run ``django-admin.py --version`` to display the current Django version.

Examples of output::

    0.95

    0.96

    0.97-pre-SVN-6069

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

==================

cleanup

-------

.. django-admin:: cleanup

.. versionadded:: 1.0

Can be run as a cronjob or directly to clean out old data from the database

(only expired sessions at the moment).

compilemessages

---------------

.. django-admin:: compilemessages

.. versionchanged:: 1.0

   Before 1.0 this was the "bin/compile-messages.py" command.

Compiles .po files created with ``makemessages`` to .mo files for use with

the builtin gettext support. See :doc:`/topics/i18n/index`.

Use the :djadminopt:`--locale` option to specify the locale to process.

If not provided, all locales are processed.

Example usage::

    django-admin.py compilemessages --locale=br_PT

createcachetable

----------------

.. django-admin:: createcachetable

Creates a cache table named ``tablename`` for use with the database cache

backend. See :doc:`/topics/cache` for more information.

.. versionadded:: 1.2

The :djadminopt:`--database` option can be used to specify the database

onto which the cachetable will be installed.

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

``USER``, ``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.

.. versionadded:: 1.2

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 ``ROOT_URLCONF``, so

``ROOT_URLCONF`` is followed by ``"###"`` in the output of ``diffsettings``.

Note that Django's default settings live in ``django/conf/global_settings.py``,

if you're ever curious to see the full list of defaults.

dumpdata <appname appname appname.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 ``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:: --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.

.. versionadded:: 1.0

The :djadminopt:`--exclude` option may be provided to prevent specific

applications from being dumped.

.. versionadded:: 1.1

In addition to specifying application names, you can provide a list of

individual models, in the form of ``appname.Model``. 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.

.. versionadded:: 1.2

The :djadminopt:`--database` option can be used to specify the database

onto which the data will be loaded.

.. django-admin-option:: --natural

.. versionadded:: 1.2

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. If you are dumping ``contrib.auth`` ``Permission``

objects or ``contrib.contenttypes`` ``ContentType`` objects, you should

probably be using this flag.

flush

-----

.. django-admin:: flush

Returns the database to the state it was in immediately after syncdb was

executed. This means that all data will be removed from the database, any

post-synchronization handlers will be re-executed, and the ``initial_data``

fixture will be re-installed.

The :djadminopt:`--noinput` option may be provided to suppress all user

prompts.

.. versionadded:: 1.2

The :djadminopt:`--database` option may be used to specify the database

to flush.

inspectdb

---------

.. django-admin:: inspectdb

Introspects the database tables in the database pointed-to by the

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

.. versionadded:: 1.2

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.

.. versionadded:: 1.2

The :djadminopt:`--database` option can be used to specify the database

onto which the data will be loaded.

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 ``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 ``<appname>/fixtures/foo/bar/mydata.json`` for each installed

application,  ``<dirname>/foo/bar/mydata.json`` for each directory in

``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 ``save`` methods and ``pre_save`` signals are not called.

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 ``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 and Fixtures

    Unfortunately, MySQL isn't capable of completely supporting all the

    features of Django fixtures. If you use MyISAM tables, MySQL doesn't

    support transactions or constraints, so you won't get a rollback if

    multiple transaction files are found, or validation of fixture data.

    If you use InnoDB tables, you won't be able to have any forward

    references in your data files - MySQL doesn't provide a mechanism to

    defer checking of row constraints until a transaction is committed.

Database-specific fixtures

~~~~~~~~~~~~~~~~~~~~~~~~~~

If you are in a multi-database setup, you may have fixture data that

you want to load onto one database, but not onto another. In this

situation, you can add database identifier into . If your

:setting:`DATABASES` setting has a 'master' database defined, you can

define the fixture ``mydata.master.json`` or

``mydata.master.json.gz``. This fixture will only be loaded if you

have specified that you want to load data onto the ``master``

database.

makemessages

------------

.. django-admin:: makemessages

.. versionchanged:: 1.0

   Before 1.0 this was the ``bin/make-messages.py`` command.

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 ``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").

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 to specify the locale to process.

Example usage::

    django-admin.py makemessages --locale=br_PT

.. django-admin-option:: --domain

Use the ``--domain`` or ``-d`` option to change the domain of the messages files.

Currently supported:

    * ``django`` for all ``*.py`` and ``*.html`` files (default)

    * ``djangojs`` for ``*.js`` files

.. django-admin-option:: --symlinks

.. versionadded:: 1.2

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 `glob-style pattern`_. Use multiple times to ignore more.

These patterns are used by default: ``'CVS'``, ``'.*'``, ``'*~'``

Example usage::

    django-admin.py makemessages --locale=en_US --ignore=apps/* --ignore=secret/*.html

.. _`glob-style pattern`: http://docs.python.org/library/glob.html

.. django-admin-option:: --no-default-ignore

Use the ``--no-default-ignore`` option to disable the default values of

:djadminopt:`--ignore`.

reset <appname appname ...>

---------------------------

.. django-admin:: reset

Executes the equivalent of ``sqlreset`` for the given app name(s).

The :djadminopt:`--noinput` option may be provided to suppress all user

prompts.

.. versionadded:: 1.2

The :djadminopt:`--database` option can be used to specify the alias

of the database to reset.

runfcgi [options]

-----------------

.. django-admin:: runfcgi

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`_.

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