========== Django FAQ ========== General questions ================= Why does this project exist? ---------------------------- Django grew from a very practical need: World Online, a newspaper Web operation, is responsible for building intensive Web applications on journalism deadlines. In the fast-paced newsroom, World Online often has only a matter of hours to take a complicated Web application from concept to public launch. At the same time, the World Online Web developers have consistently been perfectionists when it comes to following best practices of Web development. Thus, Django was designed not only to allow fast Web development, but *best-practice* Web development. Django would not be possible without a whole host of open-source projects -- `Apache`_, `Python`_, and `PostgreSQL`_ to name a few -- and we're thrilled to be able to give something back to the open-source community. .. _Apache: http://httpd.apache.org/ .. _Python: http://www.python.org/ .. _PostgreSQL: http://www.postgresql.org/ What does "Django" mean, and how do you pronounce it? ----------------------------------------------------- Django is named after `Django Reinhardt`_, a gypsy jazz guitarist from the 1930s to early 1950s. To this day, he's considered one of the best guitarists of all time. Listen to his music. You'll like it. Django is pronounced **JANG**-oh. Rhymes with FANG-oh. The "D" is silent. .. _Django Reinhardt: http://en.wikipedia.org/wiki/Django_Reinhardt Is Django stable? ----------------- Yes. World Online has been using Django for more than two years. Sites built on Django have weathered traffic spikes of over one million hits an hour and a number of Slashdottings. Yes, it's quite stable. Does Django scale? ------------------ Yes. Compared to development time, hardware is cheap, and so Django is designed to take advantage of as much hardware as you can throw at it. Django uses a "shared-nothing" architecture, which means you can add hardware at any level -- database servers, caching servers or Web/application servers. The framework cleanly separates components such as its database layer and application layer. And it ships with a simple-yet-powerful `cache framework`_. .. _`cache framework`: http://www.djangoproject.com/documentation/cache/ Who's behind this? ------------------ Django was developed at `World Online`_, the Web department of a newspaper in Lawrence, Kansas, USA. `Adrian Holovaty`_ Adrian is a Web developer with a background in journalism. He was lead developer at World Online for 2.5 years, during which time Django was developed and implemented on World Online's sites. Now he works for washingtonpost.com building rich, database-backed information sites, and continues to oversee Django development. He likes playing guitar (Django Reinhardt style) and hacking on side projects such as `chicagocrime.org`_. He lives in Chicago. On IRC, Adrian goes by ``adrian_h``. `Jacob Kaplan-Moss`_ Jacob is a whipper-snapper from California who spends equal time coding and cooking. He's lead developer at World Online and actively hacks on various cool side projects. He's contributed to the Python-ObjC bindings and was the first guy to figure out how to write Tivo apps in Python. Lately he's been messing with Python on the PSP. He lives in Lawrence, Kansas. On IRC, Jacob goes by ``jacobkm``. `Simon Willison`_ Simon is a well-respected Web developer from England. He had a one-year internship at World Online, during which time he and Adrian developed Django from scratch. The most enthusiastic Brit you'll ever meet, he's passionate about best practices in Web development and has maintained a well-read Web-development blog for years at http://simon.incutio.com. He works for Yahoo UK, where he managed to score the title "Hacker Liason." He lives in London. On IRC, Simon goes by ``SimonW``. `Wilson Miner`_ Wilson's design-fu makes us all look like rock stars. When not sneaking into apartment complex swimming pools, he's the Commercial Development Director for World Online, which means he makes the money that pays all our paychecks. He lives in Lawrence, Kansas. On IRC, Wilson goes by ``wilsonian``. .. _`World Online`: http://code.djangoproject.com/wiki/WorldOnline .. _`Adrian Holovaty`: http://www.holovaty.com/ .. _`washingtonpost.com`: http://www.washingtonpost.com/ .. _`chicagocrime.org`: http://www.chicagocrime.org/ .. _`Simon Willison`: http://simon.incutio.com/ .. _`simon.incutio.com`: http://simon.incutio.com/ .. _`Jacob Kaplan-Moss`: http://www.jacobian.org/ .. _`Wilson Miner`: http://www.wilsonminer.com/ Which sites use Django? ----------------------- The Django wiki features a consistently growing `list of Django-powered sites`_. Feel free to add your Django-powered site to the list. .. _list of Django-powered sites: http://code.djangoproject.com/wiki/DjangoPoweredSites Django appears to be a MVC framework, but you call the Controller the "view", and the View the "template". How come you don't use the standard names? ----------------------------------------------------------------------------------------------------------------------------------------------------- Well, the standard names are debatable. In our interpretation of MVC, the "view" describes the data that gets presented to the user. It's not necessarily *how* the data *looks*, but *which* data is presented. The view describes *which data you see*, not *how you see it.* It's a subtle distinction. So, in our case, a "view" is the Python callback function for a particular URL, because that callback function describes which data is presented. Furthermore, it's sensible to separate content from presentation -- which is where templates come in. In Django, a "view" describes which data is presented, but a view normally delegates to a template, which describes *how* the data is presented. Where does the "controller" fit in, then? In Django's case, it's probably the framework itself: the machinery that sends a request to the appropriate view, according to the Django URL configuration. If you're hungry for acronyms, you might say that Django is a "MTV" framework -- that is, "model", "template", and "view." That breakdown makes much more sense. At the end of the day, of course, it comes down to getting stuff done. And, regardless of how things are named, Django gets stuff done in a way that's most logical to us. does -- why doesn't Django? ----------------------------------------------------- We're well aware that there are other awesome Web frameworks out there, and we're not adverse to borrowing ideas where appropriate. However, Django was developed precisely because we were unhappy with the status quo, so please be aware that "because " does it is not going to be sufficient reason to add a given feature to Django. Why did you write all of Django from scratch, instead of using other Python libraries? -------------------------------------------------------------------------------------- When Django was originally written a couple of years ago, Adrian and Simon spent quite a bit of time exploring the various Python Web frameworks available. In our opinion, none of them were completely up to snuff. We're picky. You might even call us perfectionists. (With deadlines.) Over time, we stumbled across open-source libraries that did things we'd already implemented. It was reassuring to see other people solving similar problems in similar ways, but it was too late to integrate outside code: We'd already written, tested and implemented our own framework bits in several production settings -- and our own code met our needs delightfully. In most cases, however, we found that existing frameworks/tools inevitably had some sort of fundamental, fatal flaw that made us squeamish. No tool fit our philosophies 100%. Like we said: We're picky. We've documented our philosophies on the `design philosophies page`_. .. _design philosophies page: http://www.djangoproject.com/documentation/design_philosophies/ Do you have any of those nifty "screencast" things? --------------------------------------------------- You can bet your bottom they're on the way. But, since we're still hammering out a few points, we want to make sure they reflect the final state of things at Django 1.0, not some intermediary step. In other words, we don't want to spend a lot of energy creating screencasts yet, because Django APIs will shift. In the meantime, though, check out this `unofficial Django screencast`_. .. _unofficial Django screencast: http://www.throwingbeans.org/django_screencasts.html Is Django a content-management-system (CMS)? -------------------------------------------- No, Django is not a CMS, or any sort of "turnkey product" in and of itself. It's a Web framework; it's a programming tool that lets you build Web sites. For example, it doesn't make much sense to compare Django to something like Drupal_, because Django is something you use to *create* things like Drupal. Of course, Django's automatic admin site is fantastic and timesaving -- but the admin site is one module of Django the framework. Furthermore, although Django has special conveniences for building "CMS-y" apps, that doesn't mean it's not just as appropriate for building "non-CMS-y" apps (whatever that means!). .. _Drupal: http://drupal.org/ When will you release Django 1.0? --------------------------------- Short answer: When we're comfortable with Django's APIs, have added all features that we feel are necessary to earn a "1.0" status, and are ready to begin maintaining backwards compatibility. This should happen in a couple of months or so, although it's entirely possible that it could happen earlier. That translates into summer 2006. The merging of Django's `magic-removal branch`_ went a long way toward Django 1.0. Of course, you should note that `quite a few production sites`_ use Django in its current status. Don't let the lack of a 1.0 turn you off. .. _magic-removal branch: http://code.djangoproject.com/wiki/RemovingTheMagic .. _quite a few production sites: http://code.djangoproject.com/wiki/DjangoPoweredSites How can I download the Django documentation to read it offline? --------------------------------------------------------------- The Django docs are available in the ``docs`` directory of each Django tarball release. These docs are in ReST (ReStructured Text) format, and each text file corresponds to a Web page on the official Django site. Because the documentation is `stored in revision control`_, you can browse documentation changes just like you can browse code changes. Technically, the docs on Django's site are generated from the latest development versions of those ReST documents, so the docs on the Django site may offer more information than the docs that come with the latest Django release. .. _stored in revision control: http://code.djangoproject.com/browser/django/trunk/docs Installation questions ====================== How do I get started? --------------------- #. `Download the code`_. #. Install Django (read the `installation guide`_). #. Walk through the tutorial_. #. Check out the rest of the documentation_, and `ask questions`_ if you run into trouble. .. _`Download the code`: http://www.djangoproject.com/download/ .. _`installation guide`: http://www.djangoproject.com/documentation/install/ .. _tutorial: http://www.djangoproject.com/documentation/tutorial1/ .. _documentation: http://www.djangoproject.com/documentation/ .. _ask questions: http://www.djangoproject.com/community/ How do I fix the "install a later version of setuptools" error? --------------------------------------------------------------- Just run the ``ez_setup.py`` script in the Django distribution. What are Django's prerequisites? -------------------------------- Django requires Python_ 2.3 or later. No other Python libraries are required for basic Django usage. For a development environment -- if you just want to experiment with Django -- you don't need to have a separate Web server installed; Django comes with its own lightweight development server. For a production environment, we recommend `Apache 2`_ and mod_python_, although Django follows the WSGI_ spec, which means it can run on a variety of server platforms. If you want to use Django with a database, which is probably the case, you'll also need a database engine. PostgreSQL_ is recommended, because we're PostgreSQL fans, and MySQL_ and `SQLite 3`_ are also supported. .. _Python: http://www.python.org/ .. _Apache 2: http://httpd.apache.org/ .. _mod_python: http://www.modpython.org/ .. _WSGI: http://www.python.org/peps/pep-0333.html .. _PostgreSQL: http://www.postgresql.org/ .. _MySQL: http://www.mysql.com/ .. _`SQLite 3`: http://www.sqlite.org/ Do I have to use mod_python? ---------------------------- Although we recommend mod_python for production use, you don't have to use it, thanks to the fact that Django uses an arrangement called WSGI_. Django can talk to any WSGI-enabled server. The most common non-mod_python deployment setup is FastCGI. See `How to use Django with FastCGI`_ for full information. Also, see the `server arrangements wiki page`_ for other deployment strategies. If you just want to play around and develop things on your local computer, use the development Web server that comes with Django. Things should Just Work. .. _WSGI: http://www.python.org/peps/pep-0333.html .. _How to use Django with FastCGI: http://www.djangoproject.com/documentation/fastcgi/ .. _server arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements How do I install mod_python on Windows? --------------------------------------- * For Python 2.4, grab mod_python from `win32 build of mod_python for Python 2.4`_. * For Python 2.4, check out this `Django on Windows howto`_. * For Python 2.3, grab mod_python from http://www.modpython.org/ and read `Running mod_python on Apache on Windows2000`_. * Also, try this (not Windows-specific) `guide to getting mod_python working`_. .. _`win32 build of mod_python for Python 2.4`: http://www.lehuen.com/nicolas/index.php/2005/02/21/39-win32-build-of-mod_python-314-for-python-24 .. _`Django on Windows howto`: http://thinkhole.org/wp/2006/04/03/django-on-windows-howto/ .. _`Running mod_python on Apache on Windows2000`: http://groups-beta.google.com/group/comp.lang.python/msg/139af8c83a5a9d4f .. _`guide to getting mod_python working`: http://www.dscpl.com.au/articles/modpython-001.html Will Django run under shared hosting (like TextDrive or Dreamhost)? ------------------------------------------------------------------- See our `Django-friendly Web hosts`_ page. .. _`Django-friendly Web hosts`: http://code.djangoproject.com/wiki/DjangoFriendlyWebHosts Should I use the official version or development version? --------------------------------------------------------- The Django developers improve Django every day and are pretty good about not checking in broken code. We use the development code (from the Subversion repository) directly on our servers, so we consider it stable. With that in mind, we recommend that you use the latest development code, because it generally contains more features and fewer bugs than the "official" releases. Using Django ============ Why do I get an error about importing DJANGO_SETTINGS_MODULE? ------------------------------------------------------------- Make sure that: * The environment variable DJANGO_SETTINGS_MODULE is set to a fully-qualified Python module (i.e. "mysite.settings.main"). * Said module is on ``sys.path`` (``import mysite.settings.main`` should work). * The module doesn't contain syntax errors (of course). * If you're using mod_python but *not* using Django's request handler, you'll need to work around a mod_python bug related to the use of ``SetEnv``; before you import anything from Django you'll need to do the following:: os.environ.update(req.subprocess_env) (where ``req`` is the mod_python request object). I can't stand your template language. Do I have to use it? ---------------------------------------------------------- We happen to think our template engine is the best thing since chunky bacon, but we recognize that choosing a template language runs close to religion. There's nothing about Django that requires using the template language, so if you're attached to ZPT, Cheetah, or whatever, feel free to use those. Do I have to use your model/database layer? ------------------------------------------- Nope. Just like the template system, the model/database layer is decoupled from the rest of the framework. The one exception is: If you use a different database library, you won't get to use Django's automatically-generated admin site. That app is coupled to the Django database layer. How do I use image and file fields? ----------------------------------- Using a ``FileField`` or an ``ImageField`` in a model takes a few steps: #. In your settings file, define ``MEDIA_ROOT`` as the full path to a directory where you'd like Django to store uploaded files. (For performance, these files are not stored in the database.) Define ``MEDIA_URL`` as the base public URL of that directory. Make sure that this directory is writable by the Web server's user account. #. Add the ``FileField`` or ``ImageField`` to your model, making sure to define the ``upload_to`` option to tell Django to which subdirectory of ``MEDIA_ROOT`` it should upload files. #. All that will be stored in your database is a path to the file (relative to ``MEDIA_ROOT``). You'll must likely want to use the convenience ``get__url`` function provided by Django. For example, if your ``ImageField`` is called ``mug_shot``, you can get the absolute URL to your image in a template with ``{{ object.get_mug_shot_url }}``. If I make changes to a model, how do I update the database? ----------------------------------------------------------- If you don't mind clearing data, your project's ``manage.py`` utility has an option to reset the SQL for a particular application:: manage.py reset appname This drops any tables associated with ``appname`` and recreates them. If you do care about deleting data, you'll have to execute the ``ALTER TABLE`` statements manually in your database. That's the way we've always done it, because dealing with data is a very sensitive operation that we've wanted to avoid automating. That said, there's some work being done to add partially automated database-upgrade functionality. Do Django models support multiple-column primary keys? ------------------------------------------------------ No. Only single-column primary keys are supported. But this isn't an issue in practice, because there's nothing stopping you from adding other constraints (using the ``unique_together`` model option or creating the constraint directly in your database), and enforcing the uniqueness at that level. Single-column primary keys are needed for things such as the admin interface to work; e.g., you need a simple way of being able to specify an object to edit or delete. The database API ================ How can I see the raw SQL queries Django is running? ---------------------------------------------------- Make sure your Django ``DEBUG`` setting is set to ``True``. Then, just do this:: >>> from django.db import connection >>> connection.queries [{'sql': 'SELECT polls_polls.id,polls_polls.question,polls_polls.pub_date FROM polls_polls', 'time': '0.002'}] ``connection.queries`` is only available if ``DEBUG`` is ``True``. It's a list of dictionaries in order of query execution. Each dictionary has the following:: ``sql`` -- The raw SQL statement ``time`` -- How long the statement took to execute, in seconds. ``connection.queries`` includes all SQL statements -- INSERTs, UPDATES, SELECTs, etc. Each time your app hits the database, the query will be recorded. Can I use Django with a pre-existing database? ---------------------------------------------- Yes. See `Integrating with a legacy database`_. .. _`Integrating with a legacy database`: http://www.djangoproject.com/documentation/legacy_databases/ Why is Django leaking memory? ----------------------------- Django isn't known to leak memory. If you find your Django processes are allocating more and more memory, with no sign of releasing it, check to make sure your ``DEBUG`` setting is set to ``True``. If ``DEBUG`` is ``True``, then Django saves a copy of every SQL statement it has executed. (The queries are saved in ``django.db.connection.queries``. See `How can I see the raw SQL queries Django is running?`_.) To fix the problem, set ``DEBUG`` to ``False``. If you need to clear the query list manually at any point in your functions, just call ``reset_queries()``, like this:: from django import db db.reset_queries() The admin site ============== I can't log in. When I enter a valid username and password, it just brings up the login page again, with no error messages. --------------------------------------------------------------------------------------------------------------------------- The login cookie isn't being set correctly, because the domain of the cookie sent out by Django doesn't match the domain in your browser. Try these two things: * Set the ``SESSION_COOKIE_DOMAIN`` setting in your admin config file to match your domain. For example, if you're going to "http://www.mysite.com/admin/" in your browser, in "myproject.settings" you should set ``SESSION_COOKIE_DOMAIN = 'www.mysite.com'``. * Some browsers (Firefox?) don't like to accept cookies from domains that don't have dots in them. If you're running the admin site on "localhost" or another domain that doesn't have a dot in it, try going to "localhost.localdomain" or "127.0.0.1". And set ``SESSION_COOKIE_DOMAIN`` accordingly. I can't log in. When I enter a valid username and password, it brings up the login page again, with a "Please enter a correct username and password" error. ----------------------------------------------------------------------------------------------------------------------------------------------------------- If you're sure your username and password are correct, make sure your user account has ``is_active`` and ``is_staff`` set to True. The admin site only allows access to users with those two fields both set to True. How do I automatically set a field's value to the user who last edited the object in the admin? ----------------------------------------------------------------------------------------------- At this point, you can't do this. But it's an oft-requested feature, so we're discussing how it can be implemented. The problem is we don't want to couple the model layer with the admin layer with the request layer (to get the current user). It's a tricky problem. How do I limit admin access so that objects can only be edited by the users who created them? --------------------------------------------------------------------------------------------- See the answer to the previous question. My admin-site CSS and images showed up fine using the development server, but they're not displaying when using mod_python. --------------------------------------------------------------------------------------------------------------------------- See `serving the admin files`_ in the "How to use Django with mod_python" documentation. .. _serving the admin files: http://www.djangoproject.com/documentation/modpython/#serving-the-admin-files My "list_filter" contains a ManyToManyField, but the filter doesn't display. ---------------------------------------------------------------------------- Django won't bother displaying the filter for a ``ManyToManyField`` if there are fewer than two related objects. For example, if your ``list_filter`` includes ``sites``, and there's only one site in your database, it won't display a "Site" filter. In that case, filtering by site would be meaningless. How can I customize the functionality of the admin interface? ------------------------------------------------------------- You've got several options. If you want to piggyback on top of an add/change form that Django automatically generates, you can attach arbitrary JavaScript modules to the page via the model's ``class Admin`` ``js`` parameter. That parameter is a list of URLs, as strings, pointing to JavaScript modules that will be included within the admin form via a ``