1 =============================

     2 django-admin.py and manage.py

     3 =============================

     4 

     5 ``django-admin.py`` is Django's command-line utility for administrative tasks.

     6 This document outlines all it can do.

     7 

     8 In addition, ``manage.py`` is automatically created in each Django project.

     9 ``manage.py`` is a thin wrapper around ``django-admin.py`` that takes care of

    10 two 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 ``DJANGO_SETTINGS_MODULE`` environment variable so that it

    15       points to your project's ``settings.py`` file.

    16 

    17 The ``django-admin.py`` script should be on your system path if you installed

    18 Django via its ``setup.py`` utility. If it's not on your path, you can find it in

    19 ``site-packages/django/bin`` within your Python installation. Consider

    20 symlinking it from some place on your path, such as ``/usr/local/bin``.

    21 

    22 For Windows users, who do not have symlinking functionality available, you

    23 can copy ``django-admin.py`` to a location on your existing path or edit the

    24 ``PATH`` settings (under ``Settings - Control Panel - System - Advanced - Environment...``)

    25 to point to its installed location.

    26 

    27 Generally, 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

    30 Django settings files.

    31 

    32 Usage

    33 =====

    34 

    35 ``django-admin.py action [options]``

    36 

    37 ``manage.py action [options]``

    38 

    39 ``action`` should be one of the actions listed in this document. ``options``,

    40 which is optional, should be zero or more of the options listed in this

    41 document.

    42 

    43 Run ``django-admin.py --help`` to display a help message that includes a terse

    44 list of all available actions and options.

    45 

    46 Most actions take a list of ``appname``s. An ``appname`` is the basename of the

    47 package containing your models. For example, if your ``INSTALLED_APPS``

    48 contains the string ``'mysite.blog'``, the ``appname`` is ``blog``.

    49 

    50 Available actions

    51 =================

    52 

    53 adminindex [appname appname ...]

    54 --------------------------------

    55 

    56 Prints the admin-index template snippet for the given appnames.

    57 

    58 Use admin-index template snippets if you want to customize the look and feel of

    59 your admin's index page. See `Tutorial 2`_ for more information.

    60 

    61 .. _Tutorial 2: ../tutorial2/

    62 

    63 createcachetable [tablename]

    64 ----------------------------

    65 

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

    67 backend.  See the `cache documentation`_ for more information.

    68 

    69 .. _cache documentation: ../cache/

    70 

    71 dbshell

    72 -------

    73 

    74 Runs the command-line client for the database engine specified in your

    75 ``DATABASE_ENGINE`` setting, with the connection parameters specified in your

    76 ``DATABASE_USER``, ``DATABASE_PASSWORD``, etc., settings.

    77 

    78     * For PostgreSQL, this runs the ``psql`` command-line client.

    79     * For MySQL, this runs the ``mysql`` command-line client.

    80     * For SQLite, this runs the ``sqlite3`` command-line client.

    81 

    82 This command assumes the programs are on your ``PATH`` so that a simple call to

    83 the program name (``psql``, ``mysql``, ``sqlite3``) will find the program in

    84 the right place. There's no way to specify the location of the program

    85 manually.

    86 

    87 diffsettings

    88 ------------

    89 

    90 Displays differences between the current settings file and Django's default

    91 settings.

    92 

    93 Settings that don't appear in the defaults are followed by ``"###"``. For

    94 example, the default settings don't define ``ROOT_URLCONF``, so

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

    96 

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

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

    99 

   100 dumpdata [appname appname ...]

   101 ------------------------------

   102 

   103 Output to standard output all data in the database associated with the named 

   104 application(s).

   105 

   106 By default, the database will be dumped in JSON format. If you want the output

   107 to be in another format, use the ``--format`` option (e.g., ``format=xml``). 

   108 You may specify any Django serialization backend (including any user specified 

   109 serialization backends named in the ``SERIALIZATION_MODULES`` setting).

   110 

   111 If no application name is provided, all installed applications will be dumped.

   112 

   113 The output of ``dumpdata`` can be used as input for ``loaddata``. 

   114 

   115 flush

   116 -----

   117 

   118 Return the database to the state it was in immediately after syncdb was 

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

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

   121 fixture will be re-installed.

   122 

   123 inspectdb

   124 ---------

   125 

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

   127 ``DATABASE_NAME`` setting and outputs a Django model module (a ``models.py``

   128 file) to standard output.

   129 

   130 Use this if you have a legacy database with which you'd like to use Django.

   131 The script will inspect the database and create a model for each table within

   132 it.

   133 

   134 As you might expect, the created models will have an attribute for every field

   135 in the table. Note that ``inspectdb`` has a few special cases in its field-name

   136 output:

   137 

   138     * If ``inspectdb`` cannot map a column's type to a model field type, it'll

   139       use ``TextField`` and will insert the Python comment

   140       ``'This field type is a guess.'`` next to the field in the generated

   141       model.

   142 

   143     * If the database column name is a Python reserved word (such as

   144       ``'pass'``, ``'class'`` or ``'for'``), ``inspectdb`` will append

   145       ``'_field'`` to the attribute name. For example, if a table has a column

   146       ``'for'``, the generated model will have a field ``'for_field'``, with

   147       the ``db_column`` attribute set to ``'for'``. ``inspectdb`` will insert

   148       the Python comment

   149       ``'Field renamed because it was a Python reserved word.'`` next to the

   150       field.

   151 

   152 This feature is meant as a shortcut, not as definitive model generation. After

   153 you run it, you'll want to look over the generated models yourself to make

   154 customizations. In particular, you'll need to rearrange models' order, so that

   155 models that refer to other models are ordered properly.

   156 

   157 Primary keys are automatically introspected for PostgreSQL, MySQL and

   158 SQLite, in which case Django puts in the ``primary_key=True`` where

   159 needed.

   160 

   161 ``inspectdb`` works with PostgreSQL, MySQL and SQLite. Foreign-key detection

   162 only works in PostgreSQL and with certain types of MySQL tables.

   163 

   164 loaddata [fixture fixture ...]

   165 ------------------------------

   166 

   167 Searches for and loads the contents of the named fixture into the database.

   168 

   169 A *Fixture* is a collection of files that contain the serialized contents of

   170 the database. Each fixture has a unique name; however, the files that

   171 comprise the fixture can be distributed over multiple directories, in

   172 multiple applications.

   173 

   174 Django will search in three locations for fixtures:

   175 

   176    1. In the ``fixtures`` directory of every installed application

   177    2. In any directory named in the ``FIXTURE_DIRS`` setting

   178    3. In the literal path named by the fixture

   179 

   180 Django will load any and all fixtures it finds in these locations that match

   181 the provided fixture names. 

   182 

   183 If the named fixture has a file extension, only fixtures of that type 

   184 will be loaded. For example::

   185 

   186     django-admin.py loaddata mydata.json

   187     

   188 would only load JSON fixtures called ``mydata``. The fixture extension 

   189 must correspond to the registered name of a serializer (e.g., ``json`` or 

   190 ``xml``).

   191 

   192 If you omit the extension, Django will search all available fixture types 

   193 for a matching fixture. For example::

   194 

   195     django-admin.py loaddata mydata

   196     

   197 would look for any fixture of any fixture type called ``mydata``. If a fixture

   198 directory contained ``mydata.json``, that fixture would be loaded

   199 as a JSON fixture. However, if two fixtures with the same name but different 

   200 fixture type are discovered (for example, if ``mydata.json`` and 

   201 ``mydata.xml`` were found in the same fixture directory), fixture 

   202 installation will be aborted, and any data installed in the call to 

   203 ``loaddata`` will be removed from the database.

   204 

   205 The fixtures that are named can include directory components. These 

   206 directories will be included in the search path. For example::

   207 

   208     django-admin.py loaddata foo/bar/mydata.json

   209  

   210 would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed 

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

   212 ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.

   213 

   214 Note that the order in which fixture files are processed is undefined. However,

   215 all fixture data is installed as a single transaction, so data in

   216 one fixture can reference data in another fixture. If the database backend

   217 supports row-level constraints, these constraints will be checked at the

   218 end of the transaction.

   219 

   220 .. admonition:: MySQL and Fixtures

   221 

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

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

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

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

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

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

   228     defer checking of row constraints until a transaction is committed.    

   229     

   230 reset [appname appname ...]

   231 ---------------------------

   232 Executes the equivalent of ``sqlreset`` for the given appnames.

   233 

   234 runfcgi [options]

   235 -----------------

   236 Starts a set of FastCGI processes suitable for use with any web server

   237 which supports the FastCGI protocol. See the `FastCGI deployment

   238 documentation`_ for details. Requires the Python FastCGI module from

   239 `flup`_.

   240 

   241 .. _FastCGI deployment documentation: ../fastcgi/

   242 .. _flup: http://www.saddi.com/software/flup/

   243 

   244 runserver [optional port number, or ipaddr:port]

   245 ------------------------------------------------

   246 

   247 Starts a lightweight development Web server on the local machine. By default,

   248 the server runs on port 8000 on the IP address 127.0.0.1. You can pass in an

   249 IP address and port number explicitly.

   250 

   251 If you run this script as a user with normal privileges (recommended), you

   252 might not have access to start a port on a low port number. Low port numbers

   253 are reserved for the superuser (root).

   254 

   255 DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through

   256 security audits or performance tests. (And that's how it's gonna stay. We're in

   257 the business of making Web frameworks, not Web servers, so improving this

   258 server to be able to handle a production environment is outside the scope of

   259 Django.)

   260 

   261 The development server automatically reloads Python code for each request, as

   262 needed. You don't need to restart the server for code changes to take effect.

   263 

   264 When you start the server, and each time you change Python code while the

   265 server is running, the server will validate all of your installed models. (See

   266 the ``validate`` command below.) If the validator finds errors, it will print

   267 them to standard output, but it won't stop the server.

   268 

   269 You can run as many servers as you want, as long as they're on separate ports.

   270 Just execute ``django-admin.py runserver`` more than once.

   271 

   272 Note that the default IP address, 127.0.0.1, is not accessible from other

   273 machines on your network. To make your development server viewable to other

   274 machines on the network, use its own IP address (e.g. ``192.168.2.1``) or

   275 ``0.0.0.0``.

   276 

   277 Examples:

   278 ~~~~~~~~~

   279 

   280 Port 7000 on IP address 127.0.0.1::

   281 

   282     django-admin.py runserver 7000

   283 

   284 Port 7000 on IP address 1.2.3.4::

   285 

   286     django-admin.py runserver 1.2.3.4:7000

   287 

   288 Serving static files with the development server

   289 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   290 

   291 By default, the development server doesn't serve any static files for your site

   292 (such as CSS files, images, things under ``MEDIA_ROOT_URL`` and so forth). If

   293 you want to configure Django to serve static media, read the `serving static files`_

   294 documentation.

   295 

   296 .. _serving static files: ../static_files/

   297 

   298 Turning off auto-reload

   299 ~~~~~~~~~~~~~~~~~~~~~~~

   300 

   301 To disable auto-reloading of code while the development server is running, use the

   302 ``--noreload`` option, like so::

   303 

   304     django-admin.py runserver --noreload

   305 

   306 shell

   307 -----

   308 

   309 Starts the Python interactive interpreter.

   310 

   311 Django will use IPython_, if it's installed. If you have IPython installed and

   312 want to force use of the "plain" Python interpreter, use the ``--plain``

   313 option, like so::

   314 

   315     django-admin.py shell --plain

   316 

   317 .. _IPython: http://ipython.scipy.org/

   318 

   319 sql [appname appname ...]

   320 -------------------------

   321 

   322 Prints the CREATE TABLE SQL statements for the given appnames.

   323 

   324 sqlall [appname appname ...]

   325 ----------------------------

   326 

   327 Prints the CREATE TABLE and initial-data SQL statements for the given appnames.

   328 

   329 Refer to the description of ``sqlinitialdata`` for an explanation of how to

   330 specify initial data.

   331 

   332 sqlclear [appname appname ...]

   333 --------------------------------------

   334 

   335 Prints the DROP TABLE SQL statements for the given appnames.

   336 

   337 sqlcustom [appname appname ...]

   338 -------------------------------

   339 

   340 Prints the custom SQL statements for the given appnames.

   341 

   342 For each model in each specified app, this command looks for the file

   343 ``<appname>/sql/<modelname>.sql``, where ``<appname>`` is the given appname and

   344 ``<modelname>`` is the model's name in lowercase. For example, if you have an

   345 app ``news`` that includes a ``Story`` model, ``sqlinitialdata`` will attempt

   346 to read a file ``news/sql/story.sql`` and append it to the output of this

   347 command.

   348 

   349 Each of the SQL files, if given, is expected to contain valid SQL. The SQL

   350 files are piped directly into the database after all of the models'

   351 table-creation statements have been executed. Use this SQL hook to make any

   352 table modifications, or insert any SQL functions into the database.

   353 

   354 Note that the order in which the SQL files are processed is undefined.

   355 

   356 sqlindexes [appname appname ...]

   357 ----------------------------------------

   358 

   359 Prints the CREATE INDEX SQL statements for the given appnames.

   360 

   361 sqlreset [appname appname ...]

   362 --------------------------------------

   363 

   364 Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given appnames.

   365 

   366 sqlsequencereset [appname appname ...]

   367 ----------------------------------------------

   368 

   369 Prints the SQL statements for resetting PostgreSQL sequences for the given

   370 appnames.

   371 

   372 See http://simon.incutio.com/archive/2004/04/21/postgres for more information.

   373 

   374 startapp [appname]

   375 ------------------

   376 

   377 Creates a Django app directory structure for the given app name in the current

   378 directory.

   379 

   380 startproject [projectname]

   381 --------------------------

   382 

   383 Creates a Django project directory structure for the given project name in the

   384 current directory.

   385 

   386 syncdb

   387 ------

   388 

   389 Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables

   390 have not already been created.

   391 

   392 Use this command when you've added new applications to your project and want to

   393 install them in the database. This includes any apps shipped with Django that

   394 might be in ``INSTALLED_APPS`` by default. When you start a new project, run

   395 this command to install the default apps.

   396 

   397 If you're installing the ``django.contrib.auth`` application, ``syncdb`` will

   398 give you the option of creating a superuser immediately.

   399 

   400 ``syncdb`` will also search for and install any fixture named ``initial_data``. 

   401 See the documentation for ``loaddata`` for details on the specification of 

   402 fixture data files.

   403 

   404 test

   405 ----

   406 

   407 Discover and run tests for all installed models.  See `Testing Django applications`_ for more information.

   408 

   409 .. _testing django applications: ../testing/

   410 

   411 validate

   412 --------

   413 

   414 Validates all installed models (according to the ``INSTALLED_APPS`` setting)

   415 and prints validation errors to standard output.

   416 

   417 Available options

   418 =================

   419 

   420 --settings

   421 ----------

   422 

   423 Example usage::

   424 

   425     django-admin.py syncdb --settings=mysite.settings

   426 

   427 Explicitly specifies the settings module to use. The settings module should be

   428 in Python package syntax, e.g. ``mysite.settings``. If this isn't provided,

   429 ``django-admin.py`` will use the ``DJANGO_SETTINGS_MODULE`` environment

   430 variable.

   431 

   432 Note that this option is unnecessary in ``manage.py``, because it takes care of

   433 setting ``DJANGO_SETTINGS_MODULE`` for you.

   434 

   435 --pythonpath

   436 ------------

   437 

   438 Example usage::

   439 

   440     django-admin.py syncdb --pythonpath='/home/djangoprojects/myproject'

   441 

   442 Adds the given filesystem path to the Python `import search path`_. If this

   443 isn't provided, ``django-admin.py`` will use the ``PYTHONPATH`` environment

   444 variable.

   445 

   446 Note that this option is unnecessary in ``manage.py``, because it takes care of

   447 setting the Python path for you.

   448 

   449 .. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html

   450 

   451 --format

   452 --------

   453 

   454 Example usage::

   455 

   456     django-admin.py dumpdata --format=xml

   457 

   458 Specifies the output format that will be used. The name provided must be the name

   459 of a registered serializer.

   460 

   461 --help

   462 ------

   463 

   464 Displays a help message that includes a terse list of all available actions and

   465 options.

   466 

   467 --indent

   468 --------

   469 

   470 Example usage::

   471 

   472     django-admin.py dumpdata --indent=4

   473 

   474 Specifies the number of spaces that will be used for indentation when 

   475 pretty-printing output. By default, output will *not* be pretty-printed.

   476 Pretty-printing will only be enabled if the indent option is provided.

   477 

   478 --noinput

   479 ---------

   480 

   481 Inform django-admin that the user should NOT be prompted for any input. Useful

   482 if the django-admin script will be executed as an unattended, automated

   483 script.

   484 

   485 --noreload

   486 ----------

   487 

   488 Disable the use of the auto-reloader when running the development server.

   489 

   490 --version

   491 ---------

   492 

   493 Displays the current Django version.

   494 

   495 Example output::

   496 

   497     0.9.1

   498     0.9.1 (SVN)

   499 

   500 --verbosity

   501 -----------

   502 

   503 Example usage::

   504 

   505     django-admin.py syncdb --verbosity=2

   506 

   507 Verbosity determines the amount of notification and debug information that

   508 will be printed to the console. '0' is no output, '1' is normal output,

   509 and `2` is verbose output.

   510 

   511 --adminmedia

   512 ------------

   513 

   514 Example usage::

   515     django-admin.py manage.py --adminmedia=/tmp/new-admin-style/

   516 

   517 Tells Django where to find the various CSS and JavaScript files for the admin

   518 interface when running the development server. Normally these files are served

   519 out of the Django source tree, but because some designers customize these files

   520 for their site, this option allows you to test against custom versions.

   521 

   522 Extra niceties

   523 ==============

   524 

   525 Syntax coloring

   526 ---------------

   527 

   528 The ``django-admin.py`` / ``manage.py`` commands that output SQL to standard

   529 output will use pretty color-coded output if your terminal supports

   530 ANSI-colored output. It won't use the color codes if you're piping the

   531 command's output to another program.

   532 

   533 Bash completion

   534 ---------------

   535 

   536 If you use the Bash shell, consider installing the Django bash completion

   537 script, which lives in ``extras/django_bash_completion`` in the Django

   538 distribution. It enables tab-completion of ``django-admin.py`` and

   539 ``manage.py`` commands, so you can, for instance...

   540 

   541     * Type ``django-admin.py``.

   542     * Press [TAB] to see all available options.

   543     * Type ``sql``, then [TAB], to see all available options whose names start

   544       with ``sql``.