Troubleshooting

This page contains some advice about errors and problems commonly encounteredduring the development of Django applications.

Problems running django-admin

“command not found: django-admin”

django-admin should be on your system path if youinstalled Django via python setup.py. If it’s not on your path, you canfind it in site-packages/django/bin, where site-packages is a directorywithin your Python installation. Consider symlinking to django-admin from some place on your path, such as/usr/local/bin.

If django-admin doesn’t work but django-admin.py does, you’re probablyusing a version of Django that doesn’t match the version of this documentation.django-admin is new in Django 1.7.

macOS permissions

If you’re using macOS, you may see the message “permission denied” whenyou try to run django-admin. This is because, on Unix-based systems likemacOS, a file must be marked as “executable” before it can be run as a program.To do this, open Terminal.app and navigate (using the cd command) to thedirectory where django-admin is installed, thenrun the command sudo chmod +x django-admin.

Miscellaneous

I’m getting a UnicodeDecodeError. What am I doing wrong?

This class of errors happen when a bytestring containing non-ASCII sequences istransformed into a Unicode string and the specified encoding is incorrect. Theoutput generally looks like this:

UnicodeDecodeError: 'ascii' codec can't decode byte 0x?? in position ?:
ordinal not in range(128)

The resolution mostly depends on the context, however here are two commonpitfalls producing this error:

• Your system locale may be a default ASCII locale, like the “C” locale onUNIX-like systems (can be checked by the locale command). If it’s thecase, please refer to your system documentation to learn how you can changethis to a UTF-8 locale.Related resources:

• Unicode in Django

• https://wiki.python.org/moin/UnicodeDecodeError