Tutorial should tell Windows users to run 'python django-admin.py'

[Hourann Bosci <hourannb@…>]

On Windows, when running Django with virtualenv, users need to be told to invoke the Python interpreter with django-admin.py as an argument. Currently the tutorial says to just type django-admin.py, which runs the instance of Python from the Windows file association (not the one in the virtual environment).

When that happens (running the associated python.exe rather than the virtualenv one), the module paths for the virtual environment aren't set, so the interpreter won't find the Django libraries and will throw an ImportError.

Original problem report here: ​https://groups.google.com/d/msg/django-users/EKRJWAe1znk/v_l9HV306cIJ

Steps to reproduce:

• install Python with one of the Windows installers
• download virtualenv, create and activate an environment
• run pip install Django
• now running python django-admin.py works, but django-admin.py doesn't (due to the different sys.path)

[Hourann Bosci <hourannb@…>]

Pull request: ​https://github.com/django/django/pull/547

[Ramiro Morales]

Thanks for the report, good catch.

IMHO we shouldn't special-case Windows, we simply need to tell users to always use python django-admin.py .... With this we cover different installation methods (virtualenv, etc.), platforms and are consistent with what we already suggest for manage.py (python manage.py ...)

[Hourann Bosci <hourannb@…>]

I was wondering about that -- the other note in that section, about django-admin.py not being flagged executable on OS X, would also be irrelevant if we tell people to run python django-admin.py.

I've updated my pull request with that change, and dropped the two special-case notes.

[Tim Graham]

I'm not sure the suggestion of prefixing python to django-admin.py works in all cases. For example, if I'm in a virtualenv on linux, django-admin.py works from any directory because it's on the system path. If I try to run python django-admin.py it doesn't:

$ python django-admin.py
python: can't open file 'django-admin.py': [Errno 2] No such file or directory

python manage.py is different because manage.py is in the project directory.

[Ramiro Morales]

timo,

You are right. Sorry guys for my mistake. What I meant was python /path/to/django-admin.py.

For example in the Windows case (without virtualenv but I suspect that with virtualenv the problem remains) that script gets installed in the $PYTHON_INSTALLATION_PATH\Scripts\ dir (usually C:\pythonXY\Scripts\) and, in such platform, the techniques of associating .py files to the Python interpreter available are very hackish and brittle so it is always better to use the full path and asume there is no magic execution of .py files when they are executed from the command line specfying just their name.

[Tim Graham]

Do you think it's still best to recommend all users to use that? Seems a little sad to tell unix users to have to figure out the full path to django-admin.py when plain old django-admin.py should work just fine since it gets installed to PATH, I think?

[Aymeric Augustin]

#19452 was a colorful duplicate.

[Ramiro Morales]

Replying to timo:

Do you think it's still best to recommend all users to use that? Seems a little sad to tell unix users to have to figure out the full path to django-admin.py when plain old django-admin.py should work just fine since it gets installed to PATH, I think?

Hmm no, I was thinking about a Windows-specific note. I know we having one in the first tutorial it isn´t ideal but OTHOH we already have a note for OS X and another for Linux distribution-specific details.

[daBosq]

Sorry, I'd forgotten about this bug! But it sounds like we're agreed on having a little note for Windows users? Or maybe that section of the docs could have some sort of table for the different platforms showing "here are the different ways of invoking django-admin.py", rather than a string of OS-specific notes. (The only other fix I can think of is of getting virtualenv to do something crazy like change Windows file associations on the fly ...?!)

For now, I've changed my pull request (​​https://github.com/django/django/pull/547) back to add my original note, with no other changes to the docs.

[Tim Graham]

I noticed we have the sentence: "If it didn’t work, see Troubleshooting." (referring to django-admin.py) and then a couple notes below describing failure modes. Perhaps we could move the notes and this new one to the FAQ?

[Tim Graham]

Combined the note in the pull request from Hourann with my suggestion above.

[Tim Graham <timograham@…>]

In 1e5b0fc4d0c8b5b6005dd01359e8e0145a63992a:

Fixed #19344 - Documented how to run django-admin in a virtualenv on Windows.

Thanks Hourann Bosci for the patch.

[Tim Graham <timograham@…>]

In 084a8e295916e0139f0333f029f44c773f30d847:

[1.5.X] Fixed #19344 - Documented how to run django-admin in a virtualenv on Windows.

Thanks Hourann Bosci for the patch.

Backport of 1e5b0fc4d0 from master