Opened 11 years ago

Closed 11 years ago

Last modified 11 years ago

#19344 closed Uncategorized (fixed)

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

Reported by: Hourann Bosci <hourannb@…> Owned by: nobody
Component: Documentation Version: 1.4
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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)

Attachments (1)

19344.diff (3.6 KB ) - added by Tim Graham 11 years ago.

Download all attachments as: .zip

Change History (14)

comment:1 by Hourann Bosci <hourannb@…>, 11 years ago

Has patch: set

comment:2 by Ramiro Morales, 11 years ago

Triage Stage: UnreviewedAccepted

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 ...)

comment:3 by Hourann Bosci <hourannb@…>, 11 years ago

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.

comment:4 by Tim Graham, 11 years ago

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.

comment:5 by Ramiro Morales, 11 years ago

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.

Last edited 11 years ago by Ramiro Morales (previous) (diff)

comment:6 by Tim Graham, 11 years ago

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?

comment:7 by Aymeric Augustin, 11 years ago

#19452 was a colorful duplicate.

in reply to:  6 comment:8 by Ramiro Morales, 11 years ago

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.

comment:9 by daBosq, 11 years ago

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.

comment:10 by Tim Graham, 11 years ago

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?

by Tim Graham, 11 years ago

Attachment: 19344.diff added

comment:11 by Tim Graham, 11 years ago

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

comment:12 by Tim Graham <timograham@…>, 11 years ago

Resolution: fixed
Status: newclosed

In 1e5b0fc4d0c8b5b6005dd01359e8e0145a63992a:

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

Thanks Hourann Bosci for the patch.

comment:13 by Tim Graham <timograham@…>, 11 years ago

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

Note: See TracTickets for help on using tickets.
Back to Top