PageRenderTime 50ms CodeModel.GetById 27ms RepoModel.GetById 0ms app.codeStats 0ms

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