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