| ============================= |
| django-admin.py and manage.py |
| ============================= |
| |
| ``django-admin.py`` is Django's command-line utility for administrative tasks. |
| This document outlines all it can do. |
| |
| In addition, ``manage.py`` is automatically created in each Django project. |
| ``manage.py`` is a thin wrapper around ``django-admin.py`` that takes care of |
| two things for you before delegating to ``django-admin.py``: |
| |
| * It puts your project's package on ``sys.path``. |
| |
| * It sets the ``DJANGO_SETTINGS_MODULE`` environment variable so that it |
| points to your project's ``settings.py`` file. |
| |
| The ``django-admin.py`` script should be on your system path if you installed |
| Django via its ``setup.py`` utility. If it's not on your path, you can find it in |
| ``site-packages/django/bin`` within your Python installation. Consider |
| symlinking it from some place on your path, such as ``/usr/local/bin``. |
| |
| For Windows users, who do not have symlinking functionality available, you |
| can copy ``django-admin.py`` to a location on your existing path or edit the |
| ``PATH`` settings (under ``Settings - Control Panel - System - Advanced - Environment...``) |
| to point to its installed location. |
| |
| Generally, when working on a single Django project, it's easier to use |
| ``manage.py``. Use ``django-admin.py`` with ``DJANGO_SETTINGS_MODULE``, or the |
| ``--settings`` command line option, if you need to switch between multiple |
| Django settings files. |
| |
| Usage |
| ===== |
| |
| ``django-admin.py action [options]`` |
| |
| ``manage.py action [options]`` |
| |
| ``action`` should be one of the actions listed in this document. ``options``, |
| which is optional, should be zero or more of the options listed in this |
| document. |
| |
| Run ``django-admin.py --help`` to display a help message that includes a terse |
| list of all available actions and options. |
| |
| Most actions take a list of ``appname``s. An ``appname`` is the basename of the |
| package containing your models. For example, if your ``INSTALLED_APPS`` |
| contains the string ``'mysite.blog'``, the ``appname`` is ``blog``. |
| |
| Available actions |
| ================= |
| |
| adminindex [appname appname ...] |
| -------------------------------- |
| |
| Prints the admin-index template snippet for the given appnames. |
| |
| Use admin-index template snippets if you want to customize the look and feel of |
| your admin's index page. See `Tutorial 2`_ for more information. |
| |
| .. _Tutorial 2: ../tutorial2/ |
| |
| createcachetable [tablename] |
| ---------------------------- |
| |
| Creates a cache table named ``tablename`` for use with the database cache |
| backend. See the `cache documentation`_ for more information. |
| |
| .. _cache documentation: ../cache/ |
| |
| dbshell |
| ------- |
| |
| Runs the command-line client for the database engine specified in your |
| ``DATABASE_ENGINE`` setting, with the connection parameters specified in your |
| ``DATABASE_USER``, ``DATABASE_PASSWORD``, etc., settings. |
| |
| * For PostgreSQL, this runs the ``psql`` command-line client. |
| * For MySQL, this runs the ``mysql`` command-line client. |
| * For SQLite, this runs the ``sqlite3`` command-line client. |
| |
| This command assumes the programs are on your ``PATH`` so that a simple call to |
| the program name (``psql``, ``mysql``, ``sqlite3``) will find the program in |
| the right place. There's no way to specify the location of the program |
| manually. |
| |
| diffsettings |
| ------------ |
| |
| Displays differences between the current settings file and Django's default |
| settings. |
| |
| Settings that don't appear in the defaults are followed by ``"###"``. For |
| example, the default settings don't define ``ROOT_URLCONF``, so |
| ``ROOT_URLCONF`` is followed by ``"###"`` in the output of ``diffsettings``. |
| |
| Note that Django's default settings live in ``django/conf/global_settings.py``, |
| if you're ever curious to see the full list of defaults. |
| |
| dumpdata [appname appname ...] |
| ------------------------------ |
| |
| Output to standard output all data in the database associated with the named |
| application(s). |
| |
| By default, the database will be dumped in JSON format. If you want the output |
| to be in another format, use the ``--format`` option (e.g., ``format=xml``). |
| You may specify any Django serialization backend (including any user specified |
| serialization backends named in the ``SERIALIZATION_MODULES`` setting). |
| |
| If no application name is provided, all installed applications will be dumped. |
| |
| The output of ``dumpdata`` can be used as input for ``loaddata``. |
| |
| flush |
| ----- |
| |
| Return the database to the state it was in immediately after syncdb was |
| executed. This means that all data will be removed from the database, any |
| post-synchronization handlers will be re-executed, and the ``initial_data`` |
| fixture will be re-installed. |
| |
| inspectdb |
| --------- |
| |
| Introspects the database tables in the database pointed-to by the |
| ``DATABASE_NAME`` setting and outputs a Django model module (a ``models.py`` |
| file) to standard output. |
| |
| Use this if you have a legacy database with which you'd like to use Django. |
| The script will inspect the database and create a model for each table within |
| it. |
| |
| As you might expect, the created models will have an attribute for every field |
| in the table. Note that ``inspectdb`` has a few special cases in its field-name |
| output: |
| |
| * If ``inspectdb`` cannot map a column's type to a model field type, it'll |
| use ``TextField`` and will insert the Python comment |
| ``'This field type is a guess.'`` next to the field in the generated |
| model. |
| |
| * If the database column name is a Python reserved word (such as |
| ``'pass'``, ``'class'`` or ``'for'``), ``inspectdb`` will append |
| ``'_field'`` to the attribute name. For example, if a table has a column |
| ``'for'``, the generated model will have a field ``'for_field'``, with |
| the ``db_column`` attribute set to ``'for'``. ``inspectdb`` will insert |
| the Python comment |
| ``'Field renamed because it was a Python reserved word.'`` next to the |
| field. |
| |
| This feature is meant as a shortcut, not as definitive model generation. After |
| you run it, you'll want to look over the generated models yourself to make |
| customizations. In particular, you'll need to rearrange models' order, so that |
| models that refer to other models are ordered properly. |
| |
| Primary keys are automatically introspected for PostgreSQL, MySQL and |
| SQLite, in which case Django puts in the ``primary_key=True`` where |
| needed. |
| |
| ``inspectdb`` works with PostgreSQL, MySQL and SQLite. Foreign-key detection |
| only works in PostgreSQL and with certain types of MySQL tables. |
| |
| loaddata [fixture fixture ...] |
| ------------------------------ |
| |
| Searches for and loads the contents of the named fixture into the database. |
| |
| A *Fixture* is a collection of files that contain the serialized contents of |
| the database. Each fixture has a unique name; however, the files that |
| comprise the fixture can be distributed over multiple directories, in |
| multiple applications. |
| |
| Django will search in three locations for fixtures: |
| |
| 1. In the ``fixtures`` directory of every installed application |
| 2. In any directory named in the ``FIXTURE_DIRS`` setting |
| 3. In the literal path named by the fixture |
| |
| Django will load any and all fixtures it finds in these locations that match |
| the provided fixture names. |
| |
| If the named fixture has a file extension, only fixtures of that type |
| will be loaded. For example:: |
| |
| django-admin.py loaddata mydata.json |
| |
| would only load JSON fixtures called ``mydata``. The fixture extension |
| must correspond to the registered name of a serializer (e.g., ``json`` or |
| ``xml``). |
| |
| If you omit the extension, Django will search all available fixture types |
| for a matching fixture. For example:: |
| |
| django-admin.py loaddata mydata |
| |
| would look for any fixture of any fixture type called ``mydata``. If a fixture |
| directory contained ``mydata.json``, that fixture would be loaded |
| as a JSON fixture. However, if two fixtures with the same name but different |
| fixture type are discovered (for example, if ``mydata.json`` and |
| ``mydata.xml`` were found in the same fixture directory), fixture |
| installation will be aborted, and any data installed in the call to |
| ``loaddata`` will be removed from the database. |
| |
| The fixtures that are named can include directory components. These |
| directories will be included in the search path. For example:: |
| |
| django-admin.py loaddata foo/bar/mydata.json |
| |
| would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed |
| application, ``<dirname>/foo/bar/mydata.json`` for each directory in |
| ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``. |
| |
| Note that the order in which fixture files are processed is undefined. However, |
| all fixture data is installed as a single transaction, so data in |
| one fixture can reference data in another fixture. If the database backend |
| supports row-level constraints, these constraints will be checked at the |
| end of the transaction. |
| |
| .. admonition:: MySQL and Fixtures |
| |
| Unfortunately, MySQL isn't capable of completely supporting all the |
| features of Django fixtures. If you use MyISAM tables, MySQL doesn't |
| support transactions or constraints, so you won't get a rollback if |
| multiple transaction files are found, or validation of fixture data. |
| If you use InnoDB tables, you won't be able to have any forward |
| references in your data files - MySQL doesn't provide a mechanism to |
| defer checking of row constraints until a transaction is committed. |
| |
| reset [appname appname ...] |
| --------------------------- |
| Executes the equivalent of ``sqlreset`` for the given appnames. |
| |
| runfcgi [options] |
| ----------------- |
| Starts a set of FastCGI processes suitable for use with any web server |
| which supports the FastCGI protocol. See the `FastCGI deployment |
| documentation`_ for details. Requires the Python FastCGI module from |
| `flup`_. |
| |
| .. _FastCGI deployment documentation: ../fastcgi/ |
| .. _flup: http://www.saddi.com/software/flup/ |
| |
| runserver [optional port number, or ipaddr:port] |
| ------------------------------------------------ |
| |
| Starts a lightweight development Web server on the local machine. By default, |
| the server runs on port 8000 on the IP address 127.0.0.1. You can pass in an |
| IP address and port number explicitly. |
| |
| If you run this script as a user with normal privileges (recommended), you |
| might not have access to start a port on a low port number. Low port numbers |
| are reserved for the superuser (root). |
| |
| DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through |
| security audits or performance tests. (And that's how it's gonna stay. We're in |
| the business of making Web frameworks, not Web servers, so improving this |
| server to be able to handle a production environment is outside the scope of |
| Django.) |
| |
| The development server automatically reloads Python code for each request, as |
| needed. You don't need to restart the server for code changes to take effect. |
| |
| When you start the server, and each time you change Python code while the |
| server is running, the server will validate all of your installed models. (See |
| the ``validate`` command below.) If the validator finds errors, it will print |
| them to standard output, but it won't stop the server. |
| |
| You can run as many servers as you want, as long as they're on separate ports. |
| Just execute ``django-admin.py runserver`` more than once. |
| |
| Note that the default IP address, 127.0.0.1, is not accessible from other |
| machines on your network. To make your development server viewable to other |
| machines on the network, use its own IP address (e.g. ``192.168.2.1``) or |
| ``0.0.0.0``. |
| |
| Examples: |
| ~~~~~~~~~ |
| |
| Port 7000 on IP address 127.0.0.1:: |
| |
| django-admin.py runserver 7000 |
| |
| Port 7000 on IP address 1.2.3.4:: |
| |
| django-admin.py runserver 1.2.3.4:7000 |
| |
| Serving static files with the development server |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| By default, the development server doesn't serve any static files for your site |
| (such as CSS files, images, things under ``MEDIA_ROOT_URL`` and so forth). If |
| you want to configure Django to serve static media, read the `serving static files`_ |
| documentation. |
| |
| .. _serving static files: ../static_files/ |
| |
| Turning off auto-reload |
| ~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| To disable auto-reloading of code while the development server is running, use the |
| ``--noreload`` option, like so:: |
| |
| django-admin.py runserver --noreload |
| |
| shell |
| ----- |
| |
| Starts the Python interactive interpreter. |
| |
| Django will use IPython_, if it's installed. If you have IPython installed and |
| want to force use of the "plain" Python interpreter, use the ``--plain`` |
| option, like so:: |
| |
| django-admin.py shell --plain |
| |
| .. _IPython: http://ipython.scipy.org/ |
| |
| sql [appname appname ...] |
| ------------------------- |
| |
| Prints the CREATE TABLE SQL statements for the given appnames. |
| |
| sqlall [appname appname ...] |
| ---------------------------- |
| |
| Prints the CREATE TABLE and initial-data SQL statements for the given appnames. |
| |
| Refer to the description of ``sqlinitialdata`` for an explanation of how to |
| specify initial data. |
| |
| sqlclear [appname appname ...] |
| -------------------------------------- |
| |
| Prints the DROP TABLE SQL statements for the given appnames. |
| |
| sqlcustom [appname appname ...] |
| ------------------------------- |
| |
| Prints the custom SQL statements for the given appnames. |
| |
| For each model in each specified app, this command looks for the file |
| ``<appname>/sql/<modelname>.sql``, where ``<appname>`` is the given appname and |
| ``<modelname>`` is the model's name in lowercase. For example, if you have an |
| app ``news`` that includes a ``Story`` model, ``sqlinitialdata`` will attempt |
| to read a file ``news/sql/story.sql`` and append it to the output of this |
| command. |
| |
| Each of the SQL files, if given, is expected to contain valid SQL. The SQL |
| files are piped directly into the database after all of the models' |
| table-creation statements have been executed. Use this SQL hook to make any |
| table modifications, or insert any SQL functions into the database. |
| |
| Note that the order in which the SQL files are processed is undefined. |
| |
| sqlindexes [appname appname ...] |
| ---------------------------------------- |
| |
| Prints the CREATE INDEX SQL statements for the given appnames. |
| |
| sqlreset [appname appname ...] |
| -------------------------------------- |
| |
| Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given appnames. |
| |
| sqlsequencereset [appname appname ...] |
| ---------------------------------------------- |
| |
| Prints the SQL statements for resetting PostgreSQL sequences for the given |
| appnames. |
| |
| See http://simon.incutio.com/archive/2004/04/21/postgres for more information. |
| |
| startapp [appname] |
| ------------------ |
| |
| Creates a Django app directory structure for the given app name in the current |
| directory. |
| |
| startproject [projectname] |
| -------------------------- |
| |
| Creates a Django project directory structure for the given project name in the |
| current directory. |
| |
| syncdb |
| ------ |
| |
| Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables |
| have not already been created. |
| |
| Use this command when you've added new applications to your project and want to |
| install them in the database. This includes any apps shipped with Django that |
| might be in ``INSTALLED_APPS`` by default. When you start a new project, run |
| this command to install the default apps. |
| |
| If you're installing the ``django.contrib.auth`` application, ``syncdb`` will |
| give you the option of creating a superuser immediately. |
| |
| ``syncdb`` will also search for and install any fixture named ``initial_data``. |
| See the documentation for ``loaddata`` for details on the specification of |
| fixture data files. |
| |
| test |
| ---- |
| |
| Discover and run tests for all installed models. See `Testing Django applications`_ for more information. |
| |
| .. _testing django applications: ../testing/ |
| |
| validate |
| -------- |
| |
| Validates all installed models (according to the ``INSTALLED_APPS`` setting) |
| and prints validation errors to standard output. |
| |
| Available options |
| ================= |
| |
| --settings |
| ---------- |
| |
| Example usage:: |
| |
| django-admin.py syncdb --settings=mysite.settings |
| |
| Explicitly specifies the settings module to use. The settings module should be |
| in Python package syntax, e.g. ``mysite.settings``. If this isn't provided, |
| ``django-admin.py`` will use the ``DJANGO_SETTINGS_MODULE`` environment |
| variable. |
| |
| Note that this option is unnecessary in ``manage.py``, because it takes care of |
| setting ``DJANGO_SETTINGS_MODULE`` for you. |
| |
| --pythonpath |
| ------------ |
| |
| Example usage:: |
| |
| django-admin.py syncdb --pythonpath='/home/djangoprojects/myproject' |
| |
| Adds the given filesystem path to the Python `import search path`_. If this |
| isn't provided, ``django-admin.py`` will use the ``PYTHONPATH`` environment |
| variable. |
| |
| Note that this option is unnecessary in ``manage.py``, because it takes care of |
| setting the Python path for you. |
| |
| .. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html |
| |
| --format |
| -------- |
| |
| Example usage:: |
| |
| django-admin.py dumpdata --format=xml |
| |
| Specifies the output format that will be used. The name provided must be the name |
| of a registered serializer. |
| |
| --help |
| ------ |
| |
| Displays a help message that includes a terse list of all available actions and |
| options. |
| |
| --indent |
| -------- |
| |
| Example usage:: |
| |
| django-admin.py dumpdata --indent=4 |
| |
| Specifies the number of spaces that will be used for indentation when |
| pretty-printing output. By default, output will *not* be pretty-printed. |
| Pretty-printing will only be enabled if the indent option is provided. |
| |
| --noinput |
| --------- |
| |
| Inform django-admin that the user should NOT be prompted for any input. Useful |
| if the django-admin script will be executed as an unattended, automated |
| script. |
| |
| --noreload |
| ---------- |
| |
| Disable the use of the auto-reloader when running the development server. |
| |
| --version |
| --------- |
| |
| Displays the current Django version. |
| |
| Example output:: |
| |
| 0.9.1 |
| 0.9.1 (SVN) |
| |
| --verbosity |
| ----------- |
| |
| Example usage:: |
| |
| django-admin.py syncdb --verbosity=2 |
| |
| Verbosity determines the amount of notification and debug information that |
| will be printed to the console. '0' is no output, '1' is normal output, |
| and `2` is verbose output. |
| |
| --adminmedia |
| ------------ |
| |
| Example usage:: |
| django-admin.py manage.py --adminmedia=/tmp/new-admin-style/ |
| |
| Tells Django where to find the various CSS and JavaScript files for the admin |
| interface when running the development server. Normally these files are served |
| out of the Django source tree, but because some designers customize these files |
| for their site, this option allows you to test against custom versions. |
| |
| Extra niceties |
| ============== |
| |
| Syntax coloring |
| --------------- |
| |
| The ``django-admin.py`` / ``manage.py`` commands that output SQL to standard |
| output will use pretty color-coded output if your terminal supports |
| ANSI-colored output. It won't use the color codes if you're piping the |
| command's output to another program. |
| |
| Bash completion |
| --------------- |
| |
| If you use the Bash shell, consider installing the Django bash completion |
| script, which lives in ``extras/django_bash_completion`` in the Django |
| distribution. It enables tab-completion of ``django-admin.py`` and |
| ``manage.py`` commands, so you can, for instance... |
| |
| * Type ``django-admin.py``. |
| * Press [TAB] to see all available options. |
| * Type ``sql``, then [TAB], to see all available options whose names start |
| with ``sql``. |