classification
Title: Python 3.5 docs need to clarify how to set PATH, etc
Type: Stage:
Components: Documentation, Windows Versions: Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: dalito, docs@python, ezio.melotti, larry, paul.moore, steve.dower, tim.golden, zach.ware
Priority: normal Keywords:

Created on 2015-03-09 14:14 by paul.moore, last changed 2015-09-04 09:53 by paul.moore. This issue is now closed.

Messages (10)
msg237650 - (view) Author: Paul Moore (paul.moore) * (Python committer) Date: 2015-03-09 14:14
With Python 3.5 on Windows defaulting (for all users installs) to the read-only "Program Files" directory, and with "Add Python to PATH" having problems adding the per-user "user scripts" directory to PATH, the Python 3.5 documentation needs to explain the recommended practice for running Python 3.5 from the command line on Windows. Issues that should be covered include:

- System installs with need to be run from an elevated prompt, are user installs now the recommended approach? (It's worth noting in that case that user installs re *not* recommended for older versions, as the user Scripts directory wasn't versioned until Python 3.5)
- How to add the correct directories to PATH (including the user scripts directory) - for both CMD and powershell users and in an existing shell as well as a new one (i.e, no "Python command prompt" shortcuts!)
- How to add the correct directories persistently, so they are available to all programs on startup.
- While the "py" launcher solves the problem of running Python, and some modules via -m (such as pip), many packages install console scripts which do not have an equivalent -m invocation, so "use the launcher" is not a complete solution.

The documentation should clarify where (or if) 3rd party documentation needs to comment on Windows path difficulties. For example, the pip documentation has for a long time said that the way to run pip is via the "pip" command, and until Python included the "Add to PATH" option in the installer, we regularly had to deal with user queries because the "pip" command didn't work out of the box - it would be unfortunate if Python 3.5 left 3rd parties back in that situation again.
msg237678 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2015-03-09 17:13
FYI, the docs in the Python 3.5.0a2 CHM are newer than what's on docs.p.o, specifically the "Using Python on Windows" section. (Apparently I need to do something other than commit changes to get the website updated?)

https://hg.python.org/cpython/file/tip/Doc/using/windows.rst

The section on setting environment variables has been updated since 3.4, but it could be extended further.
msg237679 - (view) Author: Paul Moore (paul.moore) * (Python committer) Date: 2015-03-09 17:24
At a minimum, the example should show adding setting the 2 script directories to PATH, and not just sys.prefix.
msg237707 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2015-03-09 21:20
Steve, how does https://docs.python.org/dev/using/windows.html look now?  (There may have been an update lag.)
msg237708 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2015-03-09 21:25
Looks good, thanks Ned.
msg237822 - (view) Author: David Linke (dalito) * Date: 2015-03-10 22:55
Besides clarifying documentation, it may be helpful to provide a script that (temporarily) sets the path to pythonX and pythonX/scripts. A batch cmd script that does that and also changes the default Python for the launcher is here: https://gist.github.com/dalito/8356483ac2ffb2b8b468
The Python version is specified just like for the launcher: "pypath -3.4" temporarily sets the path for Python34 and Python34/scripts and "pypath" restores the previous state. The script uses the launcher to get the location of the specified Python version.

I think some of the problem above could be mitigated by including such cmd/powershell script(s).
msg237823 - (view) Author: Paul Moore (paul.moore) * (Python committer) Date: 2015-03-10 23:02
Steve has something like that planned, I believe. It's been discussed a couple of times on python-dev
msg237835 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2015-03-11 02:03
"Planned" is a bit strong - in need of some simultaneous time and motivation :) Thanks for the upvote.
msg249726 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-09-04 07:09
Can we close this out?
msg249747 - (view) Author: Paul Moore (paul.moore) * (Python committer) Date: 2015-09-04 09:53
Now that "Add Python to PATH" is an option on the front screen of the installer (not hidden behind the scary "customize" option) this can be closed.

I recall Steve suggesting there might be issues with the way a user install results in the path entries coming after the system path, but let's not worry about those unless we get specific issue reports.
History
Date User Action Args
2015-09-04 09:53:33paul.mooresetpriority: deferred blocker -> normal
status: open -> closed
resolution: fixed
messages: + msg249747
2015-09-04 07:09:16larrysetnosy: + larry
messages: + msg249726
2015-07-21 07:05:19ethan.furmansetnosy: - ethan.furman
2015-07-05 00:59:15larrysetpriority: release blocker -> deferred blocker
2015-03-13 17:59:42ezio.melottisetnosy: + ezio.melotti
2015-03-11 02:03:19steve.dowersetmessages: + msg237835
2015-03-10 23:02:02paul.mooresetmessages: + msg237823
2015-03-10 22:55:33dalitosetmessages: + msg237822
2015-03-09 21:27:12ned.deilysetnosy: - ned.deily
2015-03-09 21:25:36steve.dowersetmessages: + msg237708
2015-03-09 21:20:14ned.deilysetnosy: + ned.deily
messages: + msg237707
2015-03-09 17:24:39paul.mooresetmessages: + msg237679
2015-03-09 17:13:48steve.dowersetmessages: + msg237678
2015-03-09 16:49:52ethan.furmansetnosy: + ethan.furman
2015-03-09 16:41:34dalitosetnosy: + dalito
2015-03-09 14:14:27paul.moorecreate