PageRenderTime 19ms CodeModel.GetById 81ms app.highlight 8ms RepoModel.GetById 22ms app.codeStats 0ms

/docs/ref/django-admin.txt

https://code.google.com/p/mango-py/
Plain Text | 1375 lines | 899 code | 476 blank | 0 comment | 0 complexity | 0f5802ee848e1e145d9360392904aada MD5 | raw file
   1=============================
   2django-admin.py and manage.py
   3=============================
   4
   5``django-admin.py`` is Django's command-line utility for administrative tasks.
   6This document outlines all it can do.
   7
   8In addition, ``manage.py`` is automatically created in each Django project.
   9``manage.py`` is a thin wrapper around ``django-admin.py`` that takes care of
  10two things for you before delegating to ``django-admin.py``:
  11
  12    * It puts your project's package on ``sys.path``.
  13
  14    * It sets the :envvar:`DJANGO_SETTINGS_MODULE` environment variable so that
  15      it points to your project's ``settings.py`` file.
  16
  17The ``django-admin.py`` script should be on your system path if you installed
  18Django via its ``setup.py`` utility. If it's not on your path, you can find it
  19in ``site-packages/django/bin`` within your Python installation. Consider
  20symlinking it from some place on your path, such as ``/usr/local/bin``.
  21
  22For Windows users, who do not have symlinking functionality available, you can
  23copy ``django-admin.py`` to a location on your existing path or edit the
  24``PATH`` settings (under ``Settings - Control Panel - System - Advanced -
  25Environment...``) to point to its installed location.
  26
  27Generally, when working on a single Django project, it's easier to use
  28``manage.py``. Use ``django-admin.py`` with ``DJANGO_SETTINGS_MODULE``, or the
  29``--settings`` command line option, if you need to switch between multiple
  30Django settings files.
  31
  32The command-line examples throughout this document use ``django-admin.py`` to
  33be consistent, but any example can use ``manage.py`` just as well.
  34
  35Usage
  36=====
  37
  38.. code-block:: bash
  39
  40    django-admin.py <command> [options]
  41    manage.py <command> [options]
  42
  43``command`` should be one of the commands listed in this document.
  44``options``, which is optional, should be zero or more of the options available
  45for the given command.
  46
  47Getting runtime help
  48--------------------
  49
  50.. django-admin-option:: --help
  51
  52Run ``django-admin.py help`` to display a list of all available commands.
  53Run ``django-admin.py help <command>`` to display a description of the
  54given command and a list of its available options.
  55
  56App names
  57---------
  58
  59Many commands take a list of "app names." An "app name" is the basename of
  60the package containing your models. For example, if your :setting:`INSTALLED_APPS`
  61contains the string ``'mysite.blog'``, the app name is ``blog``.
  62
  63Determining the version
  64-----------------------
  65
  66.. django-admin-option:: --version
  67
  68Run ``django-admin.py --version`` to display the current Django version.
  69
  70Examples of output::
  71
  72    0.95
  73    0.96
  74    0.97-pre-SVN-6069
  75
  76Displaying debug output
  77-----------------------
  78
  79Use :djadminopt:`--verbosity` to specify the amount of notification and debug information
  80that ``django-admin.py`` should print to the console. For more details, see the
  81documentation for the :djadminopt:`--verbosity` option.
  82
  83Available commands
  84==================
  85
  86cleanup
  87-------
  88
  89.. django-admin:: cleanup
  90
  91Can be run as a cronjob or directly to clean out old data from the database
  92(only expired sessions at the moment).
  93
  94compilemessages
  95---------------
  96
  97.. django-admin:: compilemessages
  98
  99Compiles .po files created with ``makemessages`` to .mo files for use with
 100the builtin gettext support. See :doc:`/topics/i18n/index`.
 101
 102Use the :djadminopt:`--locale` option to specify the locale to process.
 103If not provided, all locales are processed.
 104
 105Example usage::
 106
 107    django-admin.py compilemessages --locale=br_PT
 108
 109createcachetable
 110----------------
 111
 112.. django-admin:: createcachetable
 113
 114Creates a cache table named ``tablename`` for use with the database cache
 115backend. See :doc:`/topics/cache` for more information.
 116
 117.. versionadded:: 1.2
 118
 119The :djadminopt:`--database` option can be used to specify the database
 120onto which the cachetable will be installed.
 121
 122dbshell
 123-------
 124
 125.. django-admin:: dbshell
 126
 127Runs the command-line client for the database engine specified in your
 128``ENGINE`` setting, with the connection parameters specified in your
 129:setting:`USER`, :setting:`PASSWORD`, etc., settings.
 130
 131    * For PostgreSQL, this runs the ``psql`` command-line client.
 132    * For MySQL, this runs the ``mysql`` command-line client.
 133    * For SQLite, this runs the ``sqlite3`` command-line client.
 134
 135This command assumes the programs are on your ``PATH`` so that a simple call to
 136the program name (``psql``, ``mysql``, ``sqlite3``) will find the program in
 137the right place. There's no way to specify the location of the program
 138manually.
 139
 140.. versionadded:: 1.2
 141
 142The :djadminopt:`--database` option can be used to specify the database
 143onto which to open a shell.
 144
 145diffsettings
 146------------
 147
 148.. django-admin:: diffsettings
 149
 150Displays differences between the current settings file and Django's default
 151settings.
 152
 153Settings that don't appear in the defaults are followed by ``"###"``. For
 154example, the default settings don't define :setting:`ROOT_URLCONF`, so
 155:setting:`ROOT_URLCONF` is followed by ``"###"`` in the output of
 156``diffsettings``.
 157
 158Note that Django's default settings live in ``django/conf/global_settings.py``,
 159if you're ever curious to see the full list of defaults.
 160
 161dumpdata <appname appname appname.Model ...>
 162--------------------------------------------
 163
 164.. django-admin:: dumpdata
 165
 166Outputs to standard output all data in the database associated with the named
 167application(s).
 168
 169If no application name is provided, all installed applications will be dumped.
 170
 171The output of ``dumpdata`` can be used as input for ``loaddata``.
 172
 173Note that ``dumpdata`` uses the default manager on the model for selecting the
 174records to dump. If you're using a :ref:`custom manager <custom-managers>` as
 175the default manager and it filters some of the available records, not all of the
 176objects will be dumped.
 177
 178.. versionadded:: 1.3
 179
 180The :djadminopt:`--all` option may be provided to specify that
 181``dumpdata`` should use Django's base manager, dumping records which
 182might otherwise be filtered or modified by a custom manager.
 183
 184.. django-admin-option:: --format <fmt>
 185
 186By default, ``dumpdata`` will format its output in JSON, but you can use the
 187``--format`` option to specify another format. Currently supported formats
 188are listed in :ref:`serialization-formats`.
 189
 190.. django-admin-option:: --indent <num>
 191
 192By default, ``dumpdata`` will output all data on a single line. This isn't
 193easy for humans to read, so you can use the ``--indent`` option to
 194pretty-print the output with a number of indentation spaces.
 195
 196The :djadminopt:`--exclude` option may be provided to prevent specific
 197applications from being dumped.
 198
 199.. versionadded:: 1.3
 200
 201The :djadminopt:`--exclude` option may also be provided to prevent specific
 202models (specified as in the form of ``appname.ModelName``) from being dumped.
 203
 204In addition to specifying application names, you can provide a list of
 205individual models, in the form of ``appname.Model``. If you specify a model
 206name to ``dumpdata``, the dumped output will be restricted to that model,
 207rather than the entire application. You can also mix application names and
 208model names.
 209
 210.. versionadded:: 1.2
 211
 212The :djadminopt:`--database` option can be used to specify the database
 213onto which the data will be loaded.
 214
 215.. django-admin-option:: --natural
 216
 217.. versionadded:: 1.2
 218
 219Use :ref:`natural keys <topics-serialization-natural-keys>` to represent
 220any foreign key and many-to-many relationship with a model that provides
 221a natural key definition. If you are dumping ``contrib.auth`` ``Permission``
 222objects or ``contrib.contenttypes`` ``ContentType`` objects, you should
 223probably be using this flag.
 224
 225flush
 226-----
 227
 228.. django-admin:: flush
 229
 230Returns the database to the state it was in immediately after syncdb was
 231executed. This means that all data will be removed from the database, any
 232post-synchronization handlers will be re-executed, and the ``initial_data``
 233fixture will be re-installed.
 234
 235The :djadminopt:`--noinput` option may be provided to suppress all user
 236prompts.
 237
 238.. versionadded:: 1.2
 239
 240The :djadminopt:`--database` option may be used to specify the database
 241to flush.
 242
 243inspectdb
 244---------
 245
 246.. django-admin:: inspectdb
 247
 248Introspects the database tables in the database pointed-to by the
 249:setting:`NAME` setting and outputs a Django model module (a ``models.py``
 250file) to standard output.
 251
 252Use this if you have a legacy database with which you'd like to use Django.
 253The script will inspect the database and create a model for each table within
 254it.
 255
 256As you might expect, the created models will have an attribute for every field
 257in the table. Note that ``inspectdb`` has a few special cases in its field-name
 258output:
 259
 260    * If ``inspectdb`` cannot map a column's type to a model field type, it'll
 261      use ``TextField`` and will insert the Python comment
 262      ``'This field type is a guess.'`` next to the field in the generated
 263      model.
 264
 265    * If the database column name is a Python reserved word (such as
 266      ``'pass'``, ``'class'`` or ``'for'``), ``inspectdb`` will append
 267      ``'_field'`` to the attribute name. For example, if a table has a column
 268      ``'for'``, the generated model will have a field ``'for_field'``, with
 269      the ``db_column`` attribute set to ``'for'``. ``inspectdb`` will insert
 270      the Python comment
 271      ``'Field renamed because it was a Python reserved word.'`` next to the
 272      field.
 273
 274This feature is meant as a shortcut, not as definitive model generation. After
 275you run it, you'll want to look over the generated models yourself to make
 276customizations. In particular, you'll need to rearrange models' order, so that
 277models that refer to other models are ordered properly.
 278
 279Primary keys are automatically introspected for PostgreSQL, MySQL and
 280SQLite, in which case Django puts in the ``primary_key=True`` where
 281needed.
 282
 283``inspectdb`` works with PostgreSQL, MySQL and SQLite. Foreign-key detection
 284only works in PostgreSQL and with certain types of MySQL tables.
 285
 286.. versionadded:: 1.2
 287
 288The :djadminopt:`--database` option may be used to specify the
 289database to introspect.
 290
 291loaddata <fixture fixture ...>
 292------------------------------
 293
 294.. django-admin:: loaddata
 295
 296Searches for and loads the contents of the named fixture into the database.
 297
 298.. versionadded:: 1.2
 299
 300The :djadminopt:`--database` option can be used to specify the database
 301onto which the data will be loaded.
 302
 303What's a "fixture"?
 304~~~~~~~~~~~~~~~~~~~
 305
 306A *fixture* is a collection of files that contain the serialized contents of
 307the database. Each fixture has a unique name, and the files that comprise the
 308fixture can be distributed over multiple directories, in multiple applications.
 309
 310Django will search in three locations for fixtures:
 311
 312   1. In the ``fixtures`` directory of every installed application
 313   2. In any directory named in the :setting:`FIXTURE_DIRS` setting
 314   3. In the literal path named by the fixture
 315
 316Django will load any and all fixtures it finds in these locations that match
 317the provided fixture names.
 318
 319If the named fixture has a file extension, only fixtures of that type
 320will be loaded. For example::
 321
 322    django-admin.py loaddata mydata.json
 323
 324would only load JSON fixtures called ``mydata``. The fixture extension
 325must correspond to the registered name of a
 326:ref:`serializer <serialization-formats>` (e.g., ``json`` or ``xml``).
 327
 328If you omit the extensions, Django will search all available fixture types
 329for a matching fixture. For example::
 330
 331    django-admin.py loaddata mydata
 332
 333would look for any fixture of any fixture type called ``mydata``. If a fixture
 334directory contained ``mydata.json``, that fixture would be loaded
 335as a JSON fixture.
 336
 337The fixtures that are named can include directory components. These
 338directories will be included in the search path. For example::
 339
 340    django-admin.py loaddata foo/bar/mydata.json
 341
 342would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
 343application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
 344:setting:`FIXTURE_DIRS`, and the literal path ``foo/bar/mydata.json``.
 345
 346When fixture files are processed, the data is saved to the database as is.
 347Model defined ``save`` methods and ``pre_save`` signals are not called.
 348
 349Note that the order in which fixture files are processed is undefined. However,
 350all fixture data is installed as a single transaction, so data in
 351one fixture can reference data in another fixture. If the database backend
 352supports row-level constraints, these constraints will be checked at the
 353end of the transaction.
 354
 355The ``dumpdata`` command can be used to generate input for ``loaddata``.
 356
 357Compressed fixtures
 358~~~~~~~~~~~~~~~~~~~
 359
 360Fixtures may be compressed in ``zip``, ``gz``, or ``bz2`` format. For example::
 361
 362    django-admin.py loaddata mydata.json
 363
 364would look for any of ``mydata.json``, ``mydata.json.zip``,
 365``mydata.json.gz``, or ``mydata.json.bz2``.  The first file contained within a
 366zip-compressed archive is used.
 367
 368Note that if two fixtures with the same name but different
 369fixture type are discovered (for example, if ``mydata.json`` and
 370``mydata.xml.gz`` were found in the same fixture directory), fixture
 371installation will be aborted, and any data installed in the call to
 372``loaddata`` will be removed from the database.
 373
 374.. admonition:: MySQL and Fixtures
 375
 376    Unfortunately, MySQL isn't capable of completely supporting all the
 377    features of Django fixtures. If you use MyISAM tables, MySQL doesn't
 378    support transactions or constraints, so you won't get a rollback if
 379    multiple transaction files are found, or validation of fixture data.
 380    If you use InnoDB tables, you won't be able to have any forward
 381    references in your data files - MySQL doesn't provide a mechanism to
 382    defer checking of row constraints until a transaction is committed.
 383
 384Database-specific fixtures
 385~~~~~~~~~~~~~~~~~~~~~~~~~~
 386
 387If you are in a multi-database setup, you may have fixture data that
 388you want to load onto one database, but not onto another. In this
 389situation, you can add database identifier into . If your
 390:setting:`DATABASES` setting has a 'master' database defined, you can
 391define the fixture ``mydata.master.json`` or
 392``mydata.master.json.gz``. This fixture will only be loaded if you
 393have specified that you want to load data onto the ``master``
 394database.
 395
 396makemessages
 397------------
 398
 399.. django-admin:: makemessages
 400
 401Runs over the entire source tree of the current directory and pulls out all
 402strings marked for translation. It creates (or updates) a message file in the
 403conf/locale (in the django tree) or locale (for project and application)
 404directory. After making changes to the messages files you need to compile them
 405with ``compilemessages`` for use with the builtin gettext support. See the
 406:ref:`i18n documentation <how-to-create-language-files>` for details.
 407
 408.. django-admin-option:: --all
 409
 410Use the ``--all`` or ``-a`` option to update the message files for all
 411available languages.
 412
 413Example usage::
 414
 415    django-admin.py makemessages --all
 416
 417.. django-admin-option:: --extension
 418
 419Use the ``--extension`` or ``-e`` option to specify a list of file extensions
 420to examine (default: ".html").
 421
 422Example usage::
 423
 424    django-admin.py makemessages --locale=de --extension xhtml
 425
 426Separate multiple extensions with commas or use -e or --extension multiple times::
 427
 428    django-admin.py makemessages --locale=de --extension=html,txt --extension xml
 429
 430Use the :djadminopt:`--locale` option to specify the locale to process.
 431
 432Example usage::
 433
 434    django-admin.py makemessages --locale=br_PT
 435
 436.. django-admin-option:: --domain
 437
 438Use the ``--domain`` or ``-d`` option to change the domain of the messages files.
 439Currently supported:
 440
 441    * ``django`` for all ``*.py`` and ``*.html`` files (default)
 442    * ``djangojs`` for ``*.js`` files
 443
 444.. django-admin-option:: --symlinks
 445
 446.. versionadded:: 1.2
 447
 448Use the ``--symlinks`` or ``-s`` option to follow symlinks to directories when
 449looking for new translation strings.
 450
 451Example usage::
 452
 453    django-admin.py makemessages --locale=de --symlinks
 454
 455.. django-admin-option:: --ignore
 456
 457Use the ``--ignore`` or ``-i`` option to ignore files or directories matching
 458the given `glob-style pattern`_. Use multiple times to ignore more.
 459
 460These patterns are used by default: ``'CVS'``, ``'.*'``, ``'*~'``
 461
 462Example usage::
 463
 464    django-admin.py makemessages --locale=en_US --ignore=apps/* --ignore=secret/*.html
 465
 466.. _`glob-style pattern`: http://docs.python.org/library/glob.html
 467
 468.. django-admin-option:: --no-default-ignore
 469
 470Use the ``--no-default-ignore`` option to disable the default values of
 471:djadminopt:`--ignore`.
 472
 473.. django-admin-option:: --no-wrap
 474
 475.. versionadded:: 1.3
 476
 477Use the ``--no-wrap`` option to disable breaking long message lines into
 478several lines in language files.
 479
 480reset <appname appname ...>
 481---------------------------
 482
 483.. deprecated:: 1.3
 484    This command has been deprecated. The ``flush`` can be used to delete
 485    everything. You can also use ALTER TABLE or DROP TABLE statements manually.
 486
 487.. django-admin:: reset
 488
 489Executes the equivalent of ``sqlreset`` for the given app name(s).
 490
 491The :djadminopt:`--noinput` option may be provided to suppress all user
 492prompts.
 493
 494.. versionadded:: 1.2
 495
 496The :djadminopt:`--database` option can be used to specify the alias
 497of the database to reset.
 498
 499runfcgi [options]
 500-----------------
 501
 502.. django-admin:: runfcgi
 503
 504Starts a set of FastCGI processes suitable for use with any Web server that
 505supports the FastCGI protocol. See the :doc:`FastCGI deployment documentation
 506</howto/deployment/fastcgi>` for details. Requires the Python FastCGI module from
 507`flup`_.
 508
 509.. _flup: http://www.saddi.com/software/flup/
 510
 511The options accepted by this command are passed to the FastCGI library and
 512don't use the ``'--'`` prefix as is usual for other Django management commands.
 513
 514.. django-admin-option:: protocol
 515
 516``protocol=PROTOCOL``
 517
 518Protocol to use. *PROTOCOL* can be ``fcgi``, ``scgi``, ``ajp``, etc.
 519(default is ``fcgi``)
 520
 521.. django-admin-option:: host
 522
 523``host=HOSTNAME``
 524
 525Hostname to listen on.
 526
 527.. django-admin-option:: port
 528
 529``port=PORTNUM``
 530
 531Port to listen on.
 532
 533.. django-admin-option:: socket
 534
 535``socket=FILE``
 536
 537UNIX socket to listen on.
 538
 539.. django-admin-option:: method
 540
 541``method=IMPL``
 542
 543Possible values: ``prefork`` or ``threaded`` (default ``prefork``)
 544
 545.. django-admin-option:: maxrequests
 546
 547``maxrequests=NUMBER``
 548
 549Number of requests a child handles before it is killed and a new child is
 550forked (0 means no limit).
 551
 552.. django-admin-option:: maxspare
 553
 554``maxspare=NUMBER``
 555
 556Max number of spare processes / threads.
 557
 558.. django-admin-option:: minspare
 559
 560``minspare=NUMBER``
 561
 562Min number of spare processes / threads.
 563
 564.. django-admin-option:: maxchildren
 565
 566``maxchildren=NUMBER``
 567
 568Hard limit number of processes / threads.
 569
 570.. django-admin-option:: daemonize
 571
 572``daemonize=BOOL``
 573
 574Whether to detach from terminal.
 575
 576.. django-admin-option:: pidfile
 577
 578``pidfile=FILE``
 579
 580Write the spawned process-id to file *FILE*.
 581
 582.. django-admin-option:: workdir
 583
 584``workdir=DIRECTORY``
 585
 586Change to directory *DIRECTORY* when daemonizing.
 587
 588.. django-admin-option:: debug
 589
 590``debug=BOOL``
 591
 592Set to true to enable flup tracebacks.
 593
 594.. django-admin-option:: outlog
 595
 596``outlog=FILE``
 597
 598Write stdout to the *FILE* file.
 599
 600.. django-admin-option:: errlog
 601
 602``errlog=FILE``
 603
 604Write stderr to the *FILE* file.
 605
 606.. django-admin-option:: umask
 607
 608``umask=UMASK``
 609
 610Umask to use when daemonizing. The value is interpeted as an octal number
 611(default value is ``022``).
 612
 613Example usage::
 614
 615    django-admin.py runfcgi socket=/tmp/fcgi.sock method=prefork daemonize=true \
 616        pidfile=/var/run/django-fcgi.pid
 617
 618Run a FastCGI server as a daemon and write the spawned PID in a file.
 619
 620runserver [port or address:port]
 621--------------------------------
 622
 623.. django-admin:: runserver
 624
 625Starts a lightweight development Web server on the local machine. By default,
 626the server runs on port 8000 on the IP address ``127.0.0.1``. You can pass in an
 627IP address and port number explicitly.
 628
 629If you run this script as a user with normal privileges (recommended), you
 630might not have access to start a port on a low port number. Low port numbers
 631are reserved for the superuser (root).
 632
 633DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through
 634security audits or performance tests. (And that's how it's gonna stay. We're in
 635the business of making Web frameworks, not Web servers, so improving this
 636server to be able to handle a production environment is outside the scope of
 637Django.)
 638
 639The development server automatically reloads Python code for each request, as
 640needed. You don't need to restart the server for code changes to take effect.
 641
 642When you start the server, and each time you change Python code while the
 643server is running, the server will validate all of your installed models. (See
 644the ``validate`` command below.) If the validator finds errors, it will print
 645them to standard output, but it won't stop the server.
 646
 647You can run as many servers as you want, as long as they're on separate ports.
 648Just execute ``django-admin.py runserver`` more than once.
 649
 650Note that the default IP address, ``127.0.0.1``, is not accessible from other
 651machines on your network. To make your development server viewable to other
 652machines on the network, use its own IP address (e.g. ``192.168.2.1``) or
 653``0.0.0.0`` or ``::`` (with IPv6 enabled).
 654
 655.. versionchanged:: 1.3
 656
 657You can provide an IPv6 address surrounded by brackets
 658(e.g. ``[200a::1]:8000``). This will automatically enable IPv6 support.
 659
 660A hostname containing ASCII-only characters can also be used.
 661
 662.. django-admin-option:: --adminmedia
 663
 664Use the ``--adminmedia`` option to tell Django where to find the various CSS
 665and JavaScript files for the Django admin interface. Normally, the development
 666server serves these files out of the Django source tree magically, but you'd
 667want to use this if you made any changes to those files for your own site.
 668
 669Example usage::
 670
 671    django-admin.py runserver --adminmedia=/tmp/new-admin-style/
 672
 673.. versionchanged:: 1.3
 674
 675If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled
 676(default in new projects) the :djadmin:`runserver` command will be overriden
 677with an own :djadmin:`runserver<staticfiles-runserver>` command which doesn't
 678have the :djadminopt:`--adminmedia` option due to deprecation.
 679
 680.. django-admin-option:: --noreload
 681
 682Use the ``--noreload`` option to disable the use of the auto-reloader. This
 683means any Python code changes you make while the server is running will *not*
 684take effect if the particular Python modules have already been loaded into
 685memory.
 686
 687Example usage::
 688
 689    django-admin.py runserver --noreload
 690
 691.. django-admin-option:: --ipv6, -6
 692
 693.. versionadded:: 1.3
 694
 695Use the ``--ipv6`` (or shorter ``-6``) option to tell Django to use IPv6 for
 696the development server. This changes the default IP address from
 697``127.0.0.1`` to ``::1``.
 698
 699Example usage::
 700
 701    django-admin.py runserver --ipv6
 702
 703Examples of using different ports and addresses
 704~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 705
 706Port 8000 on IP address ``127.0.0.1``::
 707
 708    django-admin.py runserver
 709
 710Port 8000 on IP address ``1.2.3.4``::
 711
 712    django-admin.py runserver 1.2.3.4:8000
 713
 714Port 7000 on IP address ``127.0.0.1``::
 715
 716    django-admin.py runserver 7000
 717
 718Port 7000 on IP address ``1.2.3.4``::
 719
 720    django-admin.py runserver 1.2.3.4:7000
 721
 722Port 8000 on IPv6 address ``::1``::
 723
 724    django-admin.py runserver -6
 725
 726Port 7000 on IPv6 address ``::1``::
 727
 728    django-admin.py runserver -6 7000
 729
 730Port 7000 on IPv6 address ``2001:0db8:1234:5678::9``::
 731
 732    django-admin.py runserver [2001:0db8:1234:5678::9]:7000
 733
 734Port 8000 on IPv4 address of host ``localhost``::
 735
 736    django-admin.py runserver localhost:8000
 737
 738Port 8000 on IPv6 address of host ``localhost``::
 739
 740    django-admin.py runserver -6 localhost:8000
 741
 742Serving static files with the development server
 743~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 744
 745By default, the development server doesn't serve any static files for your site
 746(such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If
 747you want to configure Django to serve static media, read :doc:`/howto/static-files`.
 748
 749shell
 750-----
 751
 752.. django-admin:: shell
 753
 754Starts the Python interactive interpreter.
 755
 756Django will use IPython_ or bpython_ if either is installed. If you have a
 757rich shell installed but want to force use of the "plain" Python interpreter,
 758use the ``--plain`` option, like so::
 759
 760    django-admin.py shell --plain
 761
 762.. _IPython: http://ipython.scipy.org/
 763.. _bpython: http://bpython-interpreter.org/
 764
 765sql <appname appname ...>
 766-------------------------
 767
 768.. django-admin:: sql
 769
 770Prints the CREATE TABLE SQL statements for the given app name(s).
 771
 772.. versionadded:: 1.2
 773
 774The :djadminopt:`--database` option can be used to specify the database for
 775which to print the SQL.
 776
 777sqlall <appname appname ...>
 778----------------------------
 779
 780.. django-admin:: sqlall
 781
 782Prints the CREATE TABLE and initial-data SQL statements for the given app name(s).
 783
 784Refer to the description of ``sqlcustom`` for an explanation of how to
 785specify initial data.
 786
 787.. versionadded:: 1.2
 788
 789The :djadminopt:`--database` option can be used to specify the database for
 790which to print the SQL.
 791
 792sqlclear <appname appname ...>
 793------------------------------
 794
 795.. django-admin:: sqlclear
 796
 797Prints the DROP TABLE SQL statements for the given app name(s).
 798
 799.. versionadded:: 1.2
 800
 801The :djadminopt:`--database` option can be used to specify the database for
 802which to print the SQL.
 803
 804sqlcustom <appname appname ...>
 805-------------------------------
 806
 807.. django-admin:: sqlcustom
 808
 809Prints the custom SQL statements for the given app name(s).
 810
 811For each model in each specified app, this command looks for the file
 812``<appname>/sql/<modelname>.sql``, where ``<appname>`` is the given app name and
 813``<modelname>`` is the model's name in lowercase. For example, if you have an
 814app ``news`` that includes a ``Story`` model, ``sqlcustom`` will attempt
 815to read a file ``news/sql/story.sql`` and append it to the output of this
 816command.
 817
 818Each of the SQL files, if given, is expected to contain valid SQL. The SQL
 819files are piped directly into the database after all of the models'
 820table-creation statements have been executed. Use this SQL hook to make any
 821table modifications, or insert any SQL functions into the database.
 822
 823Note that the order in which the SQL files are processed is undefined.
 824
 825.. versionadded:: 1.2
 826
 827The :djadminopt:`--database` option can be used to specify the database for
 828which to print the SQL.
 829
 830sqlflush
 831--------
 832
 833.. django-admin:: sqlflush
 834
 835Prints the SQL statements that would be executed for the :djadmin:`flush`
 836command.
 837
 838.. versionadded:: 1.2
 839
 840The :djadminopt:`--database` option can be used to specify the database for
 841which to print the SQL.
 842
 843sqlindexes <appname appname ...>
 844--------------------------------
 845
 846.. django-admin:: sqlindexes
 847
 848Prints the CREATE INDEX SQL statements for the given app name(s).
 849
 850.. versionadded:: 1.2
 851
 852The :djadminopt:`--database` option can be used to specify the database for
 853which to print the SQL.
 854
 855sqlreset <appname appname ...>
 856------------------------------
 857
 858.. deprecated:: 1.3
 859    This command has been deprecated. The ``sqlflush`` can be used to delete
 860    everything. You can also use ALTER TABLE or DROP TABLE statements manually.
 861
 862.. django-admin:: sqlreset
 863
 864Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given app name(s).
 865
 866.. versionadded:: 1.2
 867
 868The :djadminopt:`--database` option can be used to specify the database for
 869which to print the SQL.
 870
 871sqlsequencereset <appname appname ...>
 872--------------------------------------
 873
 874.. django-admin:: sqlsequencereset
 875
 876Prints the SQL statements for resetting sequences for the given app name(s).
 877
 878Sequences are indexes used by some database engines to track the next available
 879number for automatically incremented fields.
 880
 881Use this command to generate SQL which will fix cases where a sequence is out
 882of sync with its automatically incremented field data.
 883
 884.. versionadded:: 1.2
 885
 886The :djadminopt:`--database` option can be used to specify the database for
 887which to print the SQL.
 888
 889startapp <appname>
 890------------------
 891
 892.. django-admin:: startapp
 893
 894Creates a Django app directory structure for the given app name in the current
 895directory.
 896
 897startproject <projectname>
 898--------------------------
 899
 900.. django-admin:: startproject
 901
 902Creates a Django project directory structure for the given project name in the
 903current directory.
 904
 905This command is disabled when the ``--settings`` option to
 906``django-admin.py`` is used, or when the environment variable
 907``DJANGO_SETTINGS_MODULE`` has been set. To re-enable it in these
 908situations, either omit the ``--settings`` option or unset
 909``DJANGO_SETTINGS_MODULE``.
 910
 911syncdb
 912------
 913
 914.. django-admin:: syncdb
 915
 916Creates the database tables for all apps in :setting:`INSTALLED_APPS` whose
 917tables have not already been created.
 918
 919Use this command when you've added new applications to your project and want to
 920install them in the database. This includes any apps shipped with Django that
 921might be in :setting:`INSTALLED_APPS` by default. When you start a new project,
 922run this command to install the default apps.
 923
 924.. admonition:: Syncdb will not alter existing tables
 925
 926   ``syncdb`` will only create tables for models which have not yet been
 927   installed. It will *never* issue ``ALTER TABLE`` statements to match
 928   changes made to a model class after installation. Changes to model classes
 929   and database schemas often involve some form of ambiguity and, in those
 930   cases, Django would have to guess at the correct changes to make. There is
 931   a risk that critical data would be lost in the process.
 932
 933   If you have made changes to a model and wish to alter the database tables
 934   to match, use the ``sql`` command to display the new SQL structure and
 935   compare that to your existing table schema to work out the changes.
 936
 937If you're installing the ``django.contrib.auth`` application, ``syncdb`` will
 938give you the option of creating a superuser immediately.
 939
 940``syncdb`` will also search for and install any fixture named ``initial_data``
 941with an appropriate extension (e.g. ``json`` or ``xml``). See the
 942documentation for ``loaddata`` for details on the specification of fixture
 943data files.
 944
 945The :djadminopt:`--noinput` option may be provided to suppress all user
 946prompts.
 947
 948.. versionadded:: 1.2
 949
 950The :djadminopt:`--database` option can be used to specify the database to
 951synchronize.
 952
 953test <app or test identifier>
 954-----------------------------
 955
 956.. django-admin:: test
 957
 958Runs tests for all installed models. See :doc:`/topics/testing` for more
 959information.
 960
 961.. versionadded:: 1.2
 962.. django-admin-option:: --failfast
 963
 964Use the :djadminopt:`--failfast` option to stop running tests and report the failure
 965immediately after a test fails.
 966
 967testserver <fixture fixture ...>
 968--------------------------------
 969
 970.. django-admin:: testserver
 971
 972Runs a Django development server (as in ``runserver``) using data from the
 973given fixture(s).
 974
 975For example, this command::
 976
 977    django-admin.py testserver mydata.json
 978
 979...would perform the following steps:
 980
 981    1. Create a test database, as described in :doc:`/topics/testing`.
 982    2. Populate the test database with fixture data from the given fixtures.
 983       (For more on fixtures, see the documentation for ``loaddata`` above.)
 984    3. Runs the Django development server (as in ``runserver``), pointed at
 985       this newly created test database instead of your production database.
 986
 987This is useful in a number of ways:
 988
 989    * When you're writing :doc:`unit tests </topics/testing>` of how your views
 990      act with certain fixture data, you can use ``testserver`` to interact with
 991      the views in a Web browser, manually.
 992
 993    * Let's say you're developing your Django application and have a "pristine"
 994      copy of a database that you'd like to interact with. You can dump your
 995      database to a fixture (using the ``dumpdata`` command, explained above),
 996      then use ``testserver`` to run your Web application with that data. With
 997      this arrangement, you have the flexibility of messing up your data
 998      in any way, knowing that whatever data changes you're making are only
 999      being made to a test database.
1000
1001Note that this server does *not* automatically detect changes to your Python
1002source code (as ``runserver`` does). It does, however, detect changes to
1003templates.
1004
1005.. django-admin-option:: --addrport [port number or ipaddr:port]
1006
1007Use ``--addrport`` to specify a different port, or IP address and port, from
1008the default of ``127.0.0.1:8000``. This value follows exactly the same format and
1009serves exactly the same function as the argument to the ``runserver`` command.
1010
1011Examples:
1012
1013To run the test server on port 7000 with ``fixture1`` and ``fixture2``::
1014
1015    django-admin.py testserver --addrport 7000 fixture1 fixture2
1016    django-admin.py testserver fixture1 fixture2 --addrport 7000
1017
1018(The above statements are equivalent. We include both of them to demonstrate
1019that it doesn't matter whether the options come before or after the fixture
1020arguments.)
1021
1022To run on 1.2.3.4:7000 with a ``test`` fixture::
1023
1024    django-admin.py testserver --addrport 1.2.3.4:7000 test
1025
1026.. versionadded:: 1.3
1027
1028The :djadminopt:`--noinput` option may be provided to suppress all user
1029prompts.
1030
1031validate
1032--------
1033
1034.. django-admin:: validate
1035
1036Validates all installed models (according to the :setting:`INSTALLED_APPS`
1037setting) and prints validation errors to standard output.
1038
1039Commands provided by applications
1040=================================
1041
1042Some commands are only available when the ``django.contrib`` application that
1043:doc:`implements </howto/custom-management-commands>` them has been
1044:setting:`enabled <INSTALLED_APPS>`. This section describes them grouped by
1045their application.
1046
1047``django.contrib.auth``
1048-----------------------
1049
1050changepassword
1051~~~~~~~~~~~~~~
1052
1053.. django-admin:: changepassword
1054
1055.. versionadded:: 1.2
1056
1057This command is only available if Django's :doc:`authentication system
1058</topics/auth>` (``django.contrib.auth``) is installed.
1059
1060Allows changing a user's password. It prompts you to enter twice the password of
1061the user given as parameter. If they both match, the new password will be
1062changed immediately. If you do not supply a user, the command will attempt to
1063change the password whose username matches the current user.
1064
1065Example usage::
1066
1067    django-admin.py changepassword ringo
1068
1069createsuperuser
1070~~~~~~~~~~~~~~~
1071
1072.. django-admin:: createsuperuser
1073
1074This command is only available if Django's :doc:`authentication system
1075</topics/auth>` (``django.contrib.auth``) is installed.
1076
1077Creates a superuser account (a user who has all permissions). This is
1078useful if you need to create an initial superuser account but did not
1079do so during ``syncdb``, or if you need to programmatically generate
1080superuser accounts for your site(s).
1081
1082When run interactively, this command will prompt for a password for
1083the new superuser account. When run non-interactively, no password
1084will be set, and the superuser account will not be able to log in until
1085a password has been manually set for it.
1086
1087.. django-admin-option:: --username
1088.. django-admin-option:: --email
1089
1090The username and e-mail address for the new account can be supplied by
1091using the ``--username`` and ``--email`` arguments on the command
1092line. If either of those is not supplied, ``createsuperuser`` will prompt for
1093it when running interactively.
1094
1095``django.contrib.gis``
1096----------------------
1097
1098ogrinspect
1099~~~~~~~~~~
1100
1101This command is only available if :doc:`GeoDjango </ref/contrib/gis/index>`
1102(``django.contrib.gis``) is installed.
1103
1104Please refer to its :djadmin:`description <ogrinspect>` in the GeoDjango
1105documentation.
1106
1107``django.contrib.sitemaps``
1108---------------------------
1109
1110ping_google
1111~~~~~~~~~~~
1112
1113This command is only available if the :doc:`Sitemaps framework
1114</ref/contrib/sitemaps>` (``django.contrib.sitemaps``) is installed.
1115
1116Please refer to its :djadmin:`description <ping_google>` in the Sitemaps
1117documentation.
1118
1119``django.contrib.staticfiles``
1120------------------------------
1121
1122collectstatic
1123~~~~~~~~~~~~~
1124
1125This command is only available if the :doc:`static files application
1126</howto/static-files>` (``django.contrib.staticfiles``) is installed.
1127
1128Please refer to its :djadmin:`description <collectstatic>` in the
1129:doc:`staticfiles </ref/contrib/staticfiles>` documentation.
1130
1131findstatic
1132~~~~~~~~~~
1133
1134This command is only available if the :doc:`static files application
1135</howto/static-files>` (``django.contrib.staticfiles``) is installed.
1136
1137Please refer to its :djadmin:`description <findstatic>` in the :doc:`staticfiles
1138</ref/contrib/staticfiles>` documentation.
1139
1140Default options
1141===============
1142
1143Although some commands may allow their own custom options, every command
1144allows for the following options:
1145
1146.. django-admin-option:: --pythonpath
1147
1148Example usage::
1149
1150    django-admin.py syncdb --pythonpath='/home/djangoprojects/myproject'
1151
1152Adds the given filesystem path to the Python `import search path`_. If this
1153isn't provided, ``django-admin.py`` will use the ``PYTHONPATH`` environment
1154variable.
1155
1156Note that this option is unnecessary in ``manage.py``, because it takes care of
1157setting the Python path for you.
1158
1159.. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html
1160
1161.. django-admin-option:: --settings
1162
1163Example usage::
1164
1165    django-admin.py syncdb --settings=mysite.settings
1166
1167Explicitly specifies the settings module to use. The settings module should be
1168in Python package syntax, e.g. ``mysite.settings``. If this isn't provided,
1169``django-admin.py`` will use the ``DJANGO_SETTINGS_MODULE`` environment
1170variable.
1171
1172Note that this option is unnecessary in ``manage.py``, because it uses
1173``settings.py`` from the current project by default.
1174
1175.. django-admin-option:: --traceback
1176
1177Example usage::
1178
1179    django-admin.py syncdb --traceback
1180
1181By default, ``django-admin.py`` will show a simple error message whenever an
1182error occurs. If you specify ``--traceback``, ``django-admin.py``  will
1183output a full stack trace whenever an exception is raised.
1184
1185.. django-admin-option:: --verbosity
1186
1187Example usage::
1188
1189    django-admin.py syncdb --verbosity 2
1190
1191Use ``--verbosity`` to specify the amount of notification and debug information
1192that ``django-admin.py`` should print to the console.
1193
1194    * ``0`` means no output.
1195    * ``1`` means normal output (default).
1196    * ``2`` means verbose output.
1197    * ``3`` means *very* verbose output.
1198
1199Common options
1200==============
1201
1202The following options are not available on every commands, but they are
1203common to a number of commands.
1204
1205.. django-admin-option:: --database
1206
1207.. versionadded:: 1.2
1208
1209Used to specify the database on which a command will operate. If not
1210specified, this option will default to an alias of ``default``.
1211
1212For example, to dump data from the database with the alias ``master``::
1213
1214    django-admin.py dumpdata --database=master
1215
1216.. django-admin-option:: --exclude
1217
1218Exclude a specific application from the applications whose contents is
1219output. For example, to specifically exclude the `auth` application from
1220the output of dumpdata, you would call::
1221
1222    django-admin.py dumpdata --exclude=auth
1223
1224If you want to exclude multiple applications, use multiple ``--exclude``
1225directives::
1226
1227    django-admin.py dumpdata --exclude=auth --exclude=contenttypes
1228
1229.. django-admin-option:: --locale
1230
1231Use the ``--locale`` or ``-l`` option to specify the locale to process.
1232If not provided all locales are processed.
1233
1234.. django-admin-option:: --noinput
1235
1236Use the ``--noinput`` option to suppress all user prompting, such as "Are
1237you sure?" confirmation messages. This is useful if ``django-admin.py`` is
1238being executed as an unattended, automated script.
1239
1240Extra niceties
1241==============
1242
1243.. _syntax-coloring:
1244
1245Syntax coloring
1246---------------
1247
1248The ``django-admin.py`` / ``manage.py`` commands will use pretty
1249color-coded output if your terminal supports ANSI-colored output. It
1250won't use the color codes if you're piping the command's output to
1251another program.
1252
1253The colors used for syntax highlighting can be customized. Django
1254ships with three color palettes:
1255
1256    * ``dark``, suited to terminals that show white text on a black
1257      background. This is the default palette.
1258
1259    * ``light``, suited to terminals that show black text on a white
1260      background.
1261
1262    * ``nocolor``, which disables syntax highlighting.
1263
1264You select a palette by setting a ``DJANGO_COLORS`` environment
1265variable to specify the palette you want to use. For example, to
1266specify the ``light`` palette under a Unix or OS/X BASH shell, you
1267would run the following at a command prompt::
1268
1269    export DJANGO_COLORS="light"
1270
1271You can also customize the colors that are used. Django specifies a
1272number of roles in which color is used:
1273
1274    * ``error`` - A major error.
1275    * ``notice`` - A minor error.
1276    * ``sql_field`` - The name of a model field in SQL.
1277    * ``sql_coltype`` - The type of a model field in SQL.
1278    * ``sql_keyword`` - A SQL keyword.
1279    * ``sql_table`` - The name of a model in SQL.
1280    * ``http_info`` - A 1XX HTTP Informational server response.
1281    * ``http_success`` - A 2XX HTTP Success server response.
1282    * ``http_not_modified`` - A 304 HTTP Not Modified server response.
1283    * ``http_redirect`` - A 3XX HTTP Redirect server response other than 304.
1284    * ``http_not_found`` - A 404 HTTP Not Found server response.
1285    * ``http_bad_request`` - A 4XX HTTP Bad Request server response other than 404.
1286    * ``http_server_error`` - A 5XX HTTP Server Error response.
1287
1288Each of these roles can be assigned a specific foreground and
1289background color, from the following list:
1290
1291    * ``black``
1292    * ``red``
1293    * ``green``
1294    * ``yellow``
1295    * ``blue``
1296    * ``magenta``
1297    * ``cyan``
1298    * ``white``
1299
1300Each of these colors can then be modified by using the following
1301display options:
1302
1303    * ``bold``
1304    * ``underscore``
1305    * ``blink``
1306    * ``reverse``
1307    * ``conceal``
1308
1309A color specification follows one of the following patterns:
1310
1311    * ``role=fg``
1312    * ``role=fg/bg``
1313    * ``role=fg,option,option``
1314    * ``role=fg/bg,option,option``
1315
1316where ``role`` is the name of a valid color role, ``fg`` is the
1317foreground color, ``bg`` is the background color and each ``option``
1318is one of the color modifying options. Multiple color specifications
1319are then separated by semicolon. For example::
1320
1321    export DJANGO_COLORS="error=yellow/blue,blink;notice=magenta"
1322
1323would specify that errors be displayed using blinking yellow on blue,
1324and notices displayed using magenta. All other color roles would be
1325left uncolored.
1326
1327Colors can also be specified by extending a base palette. If you put
1328a palette name in a color specification, all the colors implied by that
1329palette will be loaded. So::
1330
1331    export DJANGO_COLORS="light;error=yellow/blue,blink;notice=magenta"
1332
1333would specify the use of all the colors in the light color palette,
1334*except* for the colors for errors and notices which would be
1335overridden as specified.
1336
1337Bash completion
1338---------------
1339
1340If you use the Bash shell, consider installing the Django bash completion
1341script, which lives in ``extras/django_bash_completion`` in the Django
1342distribution. It enables tab-completion of ``django-admin.py`` and
1343``manage.py`` commands, so you can, for instance...
1344
1345    * Type ``django-admin.py``.
1346    * Press [TAB] to see all available options.
1347    * Type ``sql``, then [TAB], to see all available options whose names start
1348      with ``sql``.
1349
1350
1351See :doc:`/howto/custom-management-commands` for how to add customized actions.
1352
1353
1354==========================================
1355Running management commands from your code
1356==========================================
1357
1358.. function:: django.core.management.call_command(name, *args, **options)
1359
1360To call a management command from code use ``call_command``.
1361
1362``name``
1363  the name of the command to call.
1364
1365``*args``
1366  a list of arguments accepted by the command.
1367
1368``**options``
1369  named options accepted on the command-line.
1370
1371Examples::
1372
1373      from django.core import management
1374      management.call_command('flush', verbosity=0, interactive=False)
1375      management.call_command('loaddata', 'test_data', verbosity=0)