docs/django-admin.txt

   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 The command-line examples throughout this document use ``django-admin.py`` to
  33 be consistent, but any example can use ``manage.py`` just as well.
  34
  35 Usage
  36 =====
  37
  38 ``django-admin.py action [options]``
  39
  40 ``manage.py action [options]``
  41
  42 ``action`` should be one of the actions listed in this document. ``options``,
  43 which is optional, should be zero or more of the options listed in this
  44 document.
  45
  46 Run ``django-admin.py --help`` to display a help message that includes a terse
  47 list of all available actions and options.
  48
  49 Most actions take a list of ``appname``s. An ``appname`` is the basename of the
  50 package containing your models. For example, if your ``INSTALLED_APPS``
  51 contains the string ``'mysite.blog'``, the ``appname`` is ``blog``.
  52
  53 Available actions
  54 =================
  55
  56 adminindex [appname appname ...]
  57 --------------------------------
  58
  59 Prints the admin-index template snippet for the given appnames.
  60
  61 Use admin-index template snippets if you want to customize the look and feel of
  62 your admin's index page. See `Tutorial 2`_ for more information.
  63
  64 .. _Tutorial 2: ../tutorial02/
  65
  66 createcachetable [tablename]
  67 ----------------------------
  68
  69 Creates a cache table named ``tablename`` for use with the database cache
  70 backend.  See the `cache documentation`_ for more information.
  71
  72 .. _cache documentation: ../cache/
  73
  74 dbshell
  75 -------
  76
  77 Runs the command-line client for the database engine specified in your
  78 ``DATABASE_ENGINE`` setting, with the connection parameters specified in your
  79 ``DATABASE_USER``, ``DATABASE_PASSWORD``, etc., settings.
  80
  81     * For PostgreSQL, this runs the ``psql`` command-line client.
  82     * For MySQL, this runs the ``mysql`` command-line client.
  83     * For SQLite, this runs the ``sqlite3`` command-line client.
  84
  85 This command assumes the programs are on your ``PATH`` so that a simple call to
  86 the program name (``psql``, ``mysql``, ``sqlite3``) will find the program in
  87 the right place. There's no way to specify the location of the program
  88 manually.
  89
  90 diffsettings
  91 ------------
  92
  93 Displays differences between the current settings file and Django's default
  94 settings.
  95
  96 Settings that don't appear in the defaults are followed by ``"###"``. For
  97 example, the default settings don't define ``ROOT_URLCONF``, so
  98 ``ROOT_URLCONF`` is followed by ``"###"`` in the output of ``diffsettings``.
  99
 100 Note that Django's default settings live in ``django/conf/global_settings.py``,
 101 if you're ever curious to see the full list of defaults.
 102
 103 dumpdata [appname appname ...]
 104 ------------------------------
 105
 106 Output to standard output all data in the database associated with the named
 107 application(s).
 108
 109 By default, the database will be dumped in JSON format. If you want the output
 110 to be in another format, use the ``--format`` option (e.g., ``format=xml``).
 111 You may specify any Django serialization backend (including any user specified
 112 serialization backends named in the ``SERIALIZATION_MODULES`` setting). The
 113 ``--indent`` option can be used to pretty-print the output.
 114
 115 If no application name is provided, all installed applications will be dumped.
 116
 117 The output of ``dumpdata`` can be used as input for ``loaddata``.
 118
 119 flush
 120 -----
 121
 122 Return the database to the state it was in immediately after syncdb was
 123 executed. This means that all data will be removed from the database, any
 124 post-synchronization handlers will be re-executed, and the ``initial_data``
 125 fixture will be re-installed.
 126
 127 inspectdb
 128 ---------
 129
 130 Introspects the database tables in the database pointed-to by the
 131 ``DATABASE_NAME`` setting and outputs a Django model module (a ``models.py``
 132 file) to standard output.
 133
 134 Use this if you have a legacy database with which you'd like to use Django.
 135 The script will inspect the database and create a model for each table within
 136 it.
 137
 138 As you might expect, the created models will have an attribute for every field
 139 in the table. Note that ``inspectdb`` has a few special cases in its field-name
 140 output:
 141
 142     * If ``inspectdb`` cannot map a column's type to a model field type, it'll
 143       use ``TextField`` and will insert the Python comment
 144       ``'This field type is a guess.'`` next to the field in the generated
 145       model.
 146
 147     * If the database column name is a Python reserved word (such as
 148       ``'pass'``, ``'class'`` or ``'for'``), ``inspectdb`` will append
 149       ``'_field'`` to the attribute name. For example, if a table has a column
 150       ``'for'``, the generated model will have a field ``'for_field'``, with
 151       the ``db_column`` attribute set to ``'for'``. ``inspectdb`` will insert
 152       the Python comment
 153       ``'Field renamed because it was a Python reserved word.'`` next to the
 154       field.
 155
 156 This feature is meant as a shortcut, not as definitive model generation. After
 157 you run it, you'll want to look over the generated models yourself to make
 158 customizations. In particular, you'll need to rearrange models' order, so that
 159 models that refer to other models are ordered properly.
 160
 161 Primary keys are automatically introspected for PostgreSQL, MySQL and
 162 SQLite, in which case Django puts in the ``primary_key=True`` where
 163 needed.
 164
 165 ``inspectdb`` works with PostgreSQL, MySQL and SQLite. Foreign-key detection
 166 only works in PostgreSQL and with certain types of MySQL tables.
 167
 168 loaddata [fixture fixture ...]
 169 ------------------------------
 170
 171 Searches for and loads the contents of the named fixture into the database.
 172
 173 A *Fixture* is a collection of files that contain the serialized contents of
 174 the database. Each fixture has a unique name; however, the files that
 175 comprise the fixture can be distributed over multiple directories, in
 176 multiple applications.
 177
 178 Django will search in three locations for fixtures:
 179
 180    1. In the ``fixtures`` directory of every installed application
 181    2. In any directory named in the ``FIXTURE_DIRS`` setting
 182    3. In the literal path named by the fixture
 183
 184 Django will load any and all fixtures it finds in these locations that match
 185 the provided fixture names.
 186
 187 If the named fixture has a file extension, only fixtures of that type
 188 will be loaded. For example::
 189
 190     django-admin.py loaddata mydata.json
 191
 192 would only load JSON fixtures called ``mydata``. The fixture extension
 193 must correspond to the registered name of a serializer (e.g., ``json`` or
 194 ``xml``).
 195
 196 If you omit the extension, Django will search all available fixture types
 197 for a matching fixture. For example::
 198
 199     django-admin.py loaddata mydata
 200
 201 would look for any fixture of any fixture type called ``mydata``. If a fixture
 202 directory contained ``mydata.json``, that fixture would be loaded
 203 as a JSON fixture. However, if two fixtures with the same name but different
 204 fixture type are discovered (for example, if ``mydata.json`` and
 205 ``mydata.xml`` were found in the same fixture directory), fixture
 206 installation will be aborted, and any data installed in the call to
 207 ``loaddata`` will be removed from the database.
 208
 209 The fixtures that are named can include directory components. These
 210 directories will be included in the search path. For example::
 211
 212     django-admin.py loaddata foo/bar/mydata.json
 213
 214 would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
 215 application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
 216 ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
 217
 218 Note that the order in which fixture files are processed is undefined. However,
 219 all fixture data is installed as a single transaction, so data in
 220 one fixture can reference data in another fixture. If the database backend
 221 supports row-level constraints, these constraints will be checked at the
 222 end of the transaction.
 223
 224 The ``dumpdata`` command can be used to generate input for ``loaddata``.
 225
 226 .. admonition:: MySQL and Fixtures
 227
 228     Unfortunately, MySQL isn't capable of completely supporting all the
 229     features of Django fixtures. If you use MyISAM tables, MySQL doesn't
 230     support transactions or constraints, so you won't get a rollback if
 231     multiple transaction files are found, or validation of fixture data.
 232     If you use InnoDB tables, you won't be able to have any forward
 233     references in your data files - MySQL doesn't provide a mechanism to
 234     defer checking of row constraints until a transaction is committed.
 235
 236 reset [appname appname ...]
 237 ---------------------------
 238 Executes the equivalent of ``sqlreset`` for the given appnames.
 239
 240 runfcgi [options]
 241 -----------------
 242 Starts a set of FastCGI processes suitable for use with any web server
 243 which supports the FastCGI protocol. See the `FastCGI deployment
 244 documentation`_ for details. Requires the Python FastCGI module from
 245 `flup`_.
 246
 247 .. _FastCGI deployment documentation: ../fastcgi/
 248 .. _flup: http://www.saddi.com/software/flup/
 249
 250 runserver [optional port number, or ipaddr:port]
 251 ------------------------------------------------
 252
 253 Starts a lightweight development Web server on the local machine. By default,
 254 the server runs on port 8000 on the IP address 127.0.0.1. You can pass in an
 255 IP address and port number explicitly.
 256
 257 If you run this script as a user with normal privileges (recommended), you
 258 might not have access to start a port on a low port number. Low port numbers
 259 are reserved for the superuser (root).
 260
 261 DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through
 262 security audits or performance tests. (And that's how it's gonna stay. We're in
 263 the business of making Web frameworks, not Web servers, so improving this
 264 server to be able to handle a production environment is outside the scope of
 265 Django.)
 266
 267 The development server automatically reloads Python code for each request, as
 268 needed. You don't need to restart the server for code changes to take effect.
 269
 270 When you start the server, and each time you change Python code while the
 271 server is running, the server will validate all of your installed models. (See
 272 the ``validate`` command below.) If the validator finds errors, it will print
 273 them to standard output, but it won't stop the server.
 274
 275 You can run as many servers as you want, as long as they're on separate ports.
 276 Just execute ``django-admin.py runserver`` more than once.
 277
 278 Note that the default IP address, 127.0.0.1, is not accessible from other
 279 machines on your network. To make your development server viewable to other
 280 machines on the network, use its own IP address (e.g. ``192.168.2.1``) or
 281 ``0.0.0.0``.
 282
 283 Examples:
 284 ~~~~~~~~~
 285
 286 Port 7000 on IP address 127.0.0.1::
 287
 288     django-admin.py runserver 7000
 289
 290 Port 7000 on IP address 1.2.3.4::
 291
 292     django-admin.py runserver 1.2.3.4:7000
 293
 294 Serving static files with the development server
 295 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 296
 297 By default, the development server doesn't serve any static files for your site
 298 (such as CSS files, images, things under ``MEDIA_URL`` and so forth). If
 299 you want to configure Django to serve static media, read the `serving static files`_
 300 documentation.
 301
 302 .. _serving static files: ../static_files/
 303
 304 Turning off auto-reload
 305 ~~~~~~~~~~~~~~~~~~~~~~~
 306
 307 To disable auto-reloading of code while the development server is running, use the
 308 ``--noreload`` option, like so::
 309
 310     django-admin.py runserver --noreload
 311
 312 shell
 313 -----
 314
 315 Starts the Python interactive interpreter.
 316
 317 Django will use IPython_, if it's installed. If you have IPython installed and
 318 want to force use of the "plain" Python interpreter, use the ``--plain``
 319 option, like so::
 320
 321     django-admin.py shell --plain
 322
 323 .. _IPython: http://ipython.scipy.org/
 324
 325 sql [appname appname ...]
 326 -------------------------
 327
 328 Prints the CREATE TABLE SQL statements for the given appnames.
 329
 330 sqlall [appname appname ...]
 331 ----------------------------
 332
 333 Prints the CREATE TABLE and initial-data SQL statements for the given appnames.
 334
 335 Refer to the description of ``sqlcustom`` for an explanation of how to
 336 specify initial data.
 337
 338 sqlclear [appname appname ...]
 339 --------------------------------------
 340
 341 Prints the DROP TABLE SQL statements for the given appnames.
 342
 343 sqlcustom [appname appname ...]
 344 -------------------------------
 345
 346 Prints the custom SQL statements for the given appnames.
 347
 348 For each model in each specified app, this command looks for the file
 349 ``<appname>/sql/<modelname>.sql``, where ``<appname>`` is the given appname and
 350 ``<modelname>`` is the model's name in lowercase. For example, if you have an
 351 app ``news`` that includes a ``Story`` model, ``sqlcustom`` will attempt
 352 to read a file ``news/sql/story.sql`` and append it to the output of this
 353 command.
 354
 355 Each of the SQL files, if given, is expected to contain valid SQL. The SQL
 356 files are piped directly into the database after all of the models'
 357 table-creation statements have been executed. Use this SQL hook to make any
 358 table modifications, or insert any SQL functions into the database.
 359
 360 Note that the order in which the SQL files are processed is undefined.
 361
 362 sqlindexes [appname appname ...]
 363 ----------------------------------------
 364
 365 Prints the CREATE INDEX SQL statements for the given appnames.
 366
 367 sqlreset [appname appname ...]
 368 --------------------------------------
 369
 370 Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given appnames.
 371
 372 sqlsequencereset [appname appname ...]
 373 ----------------------------------------------
 374
 375 Prints the SQL statements for resetting sequences for the given
 376 appnames.
 377
 378 See http://simon.incutio.com/archive/2004/04/21/postgres for more information.
 379
 380 startapp [appname]
 381 ------------------
 382
 383 Creates a Django app directory structure for the given app name in the current
 384 directory.
 385
 386 startproject [projectname]
 387 --------------------------
 388
 389 Creates a Django project directory structure for the given project name in the
 390 current directory.
 391
 392 syncdb
 393 ------
 394
 395 Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables
 396 have not already been created.
 397
 398 Use this command when you've added new applications to your project and want to
 399 install them in the database. This includes any apps shipped with Django that
 400 might be in ``INSTALLED_APPS`` by default. When you start a new project, run
 401 this command to install the default apps.
 402
 403 If you're installing the ``django.contrib.auth`` application, ``syncdb`` will
 404 give you the option of creating a superuser immediately.
 405
 406 ``syncdb`` will also search for and install any fixture named ``initial_data``
 407 with an appropriate extension (e.g. ``json`` or ``xml``). See the
 408 documentation for ``loaddata`` for details on the specification of fixture
 409 data files.
 410
 411 test
 412 ----
 413
 414 Discover and run tests for all installed models.  See `Testing Django applications`_ for more information.
 415
 416 .. _testing django applications: ../testing/
 417
 418 validate
 419 --------
 420
 421 Validates all installed models (according to the ``INSTALLED_APPS`` setting)
 422 and prints validation errors to standard output.
 423
 424 Available options
 425 =================
 426
 427 --settings
 428 ----------
 429
 430 Example usage::
 431
 432     django-admin.py syncdb --settings=mysite.settings
 433
 434 Explicitly specifies the settings module to use. The settings module should be
 435 in Python package syntax, e.g. ``mysite.settings``. If this isn't provided,
 436 ``django-admin.py`` will use the ``DJANGO_SETTINGS_MODULE`` environment
 437 variable.
 438
 439 Note that this option is unnecessary in ``manage.py``, because it takes care of
 440 setting ``DJANGO_SETTINGS_MODULE`` for you.
 441
 442 --pythonpath
 443 ------------
 444
 445 Example usage::
 446
 447     django-admin.py syncdb --pythonpath='/home/djangoprojects/myproject'
 448
 449 Adds the given filesystem path to the Python `import search path`_. If this
 450 isn't provided, ``django-admin.py`` will use the ``PYTHONPATH`` environment
 451 variable.
 452
 453 Note that this option is unnecessary in ``manage.py``, because it takes care of
 454 setting the Python path for you.
 455
 456 .. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html
 457
 458 --format
 459 --------
 460
 461 Example usage::
 462
 463     django-admin.py dumpdata --format=xml
 464
 465 Specifies the output format that will be used. The name provided must be the name
 466 of a registered serializer.
 467
 468 --help
 469 ------
 470
 471 Displays a help message that includes a terse list of all available actions and
 472 options.
 473
 474 --indent
 475 --------
 476
 477 Example usage::
 478
 479     django-admin.py dumpdata --indent=4
 480
 481 Specifies the number of spaces that will be used for indentation when
 482 pretty-printing output. By default, output will *not* be pretty-printed.
 483 Pretty-printing will only be enabled if the indent option is provided.
 484
 485 --noinput
 486 ---------
 487
 488 Inform django-admin that the user should NOT be prompted for any input. Useful
 489 if the django-admin script will be executed as an unattended, automated
 490 script.
 491
 492 --noreload
 493 ----------
 494
 495 Disable the use of the auto-reloader when running the development server.
 496
 497 --version
 498 ---------
 499
 500 Displays the current Django version.
 501
 502 Example output::
 503
 504     0.9.1
 505     0.9.1 (SVN)
 506
 507 --verbosity
 508 -----------
 509
 510 Example usage::
 511
 512     django-admin.py syncdb --verbosity=2
 513
 514 Verbosity determines the amount of notification and debug information that
 515 will be printed to the console. '0' is no output, '1' is normal output,
 516 and ``2`` is verbose output.
 517
 518 --adminmedia
 519 ------------
 520
 521 Example usage::
 522
 523     django-admin.py --adminmedia=/tmp/new-admin-style/
 524
 525 Tells Django where to find the various CSS and JavaScript files for the admin
 526 interface when running the development server. Normally these files are served
 527 out of the Django source tree, but because some designers customize these files
 528 for their site, this option allows you to test against custom versions.
 529
 530 Extra niceties
 531 ==============
 532
 533 Syntax coloring
 534 ---------------
 535
 536 The ``django-admin.py`` / ``manage.py`` commands that output SQL to standard
 537 output will use pretty color-coded output if your terminal supports
 538 ANSI-colored output. It won't use the color codes if you're piping the
 539 command's output to another program.
 540
 541 Bash completion
 542 ---------------
 543
 544 If you use the Bash shell, consider installing the Django bash completion
 545 script, which lives in ``extras/django_bash_completion`` in the Django
 546 distribution. It enables tab-completion of ``django-admin.py`` and
 547 ``manage.py`` commands, so you can, for instance...
 548
 549     * Type ``django-admin.py``.
 550     * Press [TAB] to see all available options.
 551     * Type ``sql``, then [TAB], to see all available options whose names start
 552       with ``sql``.