Opened 3 years ago

Closed 2 years ago

Last modified 2 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 timo 2 years ago.

Download all attachments as: .zip

Change History (14)

comment:1 Changed 3 years ago by Hourann Bosci <hourannb@…>

  • Has patch set
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

comment:2 Changed 3 years ago by ramiro

  • Triage Stage changed from Unreviewed to Accepted

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 Changed 3 years ago by 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.

comment:4 Changed 2 years ago by timo

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 Changed 2 years ago by ramiro

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 2 years ago by ramiro (previous) (diff)

comment:6 follow-up: Changed 2 years ago by 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?

comment:7 Changed 2 years ago by aaugustin

#19452 was a colorful duplicate.

comment:8 in reply to: ↑ 6 Changed 2 years ago by ramiro

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 Changed 2 years ago by 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.

comment:10 Changed 2 years ago by timo

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?

Changed 2 years ago by timo

comment:11 Changed 2 years ago by timo

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

comment:12 Changed 2 years ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from new to closed

In 1e5b0fc4d0c8b5b6005dd01359e8e0145a63992a:

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

Thanks Hourann Bosci for the patch.

comment:13 Changed 2 years ago by 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

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