This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: PEP 453: update the "Installing Python Modules" documentation
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4
Status: closed Resolution: fixed
Dependencies: 19406 Superseder:
Assigned To: ncoghlan Nosy List: Jon Snoo, Marcus.Smith, benjamin.peterson, dstufft, eric.araujo, georg.brandl, larry, loewis, ncoghlan, python-dev
Priority: deferred blocker Keywords: patch

Created on 2013-10-26 12:44 by ncoghlan, last changed 2022-04-11 14:57 by admin. This issue is now closed.

File name Uploaded Description Edit
issue19407_packaging_docs.diff ncoghlan, 2014-03-08 14:13 WIP patch (new guides are placeholders) review
Messages (23)
msg201343 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-26 12:44
Updating the "Installing Python Modules" docs in 2.7, 3.3 and default to recommend pip as the default cross-platform installer.
msg201344 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-26 12:45
Once issue 19406 is implemented, this will need an additional update to indicate pip should be available by default in 3.4.
msg201348 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-26 12:48
Issue 19347 tracks overall PEP 453 implementation progress
msg201711 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-30 05:40
Marcus Smith (aka @qwcode) has made good strides this week in getting the Python Packaging User Guide to a presentable state using the current Python docs theme.


Accordingly, I think it makes sense to:
1. Arrange for a copy of this guide to be hosted somewhere on
2. Refer to that from the per-version distutils guides rather than referring directly to

msg201737 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-10-30 14:18
Alternative (more sensible) option - leave the packaging user guide hosted on ReadTheDocs, and if we decide to add a subdomain for it later, that won't break any existing links.
msg202531 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-11-10 15:07
Larry, just a heads up that as a docs patch that isn't directly affected by the feature freeze, I likely won't get to this one until after beta 1.

We'll make sure issue 19406 and the other functional changes are resolved, though.
msg205786 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-12-10 10:49
After reviewing the Extending & Embedding docs recently, I think a disclaimer/redirect to the tool recommendations in the Python Packaging User Guide is appropriate there as well.

Marcus also added an issue to update the distutils docs themselves:

(The user guide tracker is currently serving as a metatracker for docs issues for all the core tools)
msg205789 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-12-10 11:19
New changeset a9f91a38a265 by Nick Coghlan in branch '2.7':
Issue #19407: add Python Packaging User Guide notes
msg205792 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-12-10 11:32
New changeset 16b7536e418b by Nick Coghlan in branch '3.3':
Issue #19407: add Python Packaging User Guide notes

New changeset bc21da9727ad by Nick Coghlan in branch 'default':
Issue #19407: merge PPUG notes from 3.3
msg207175 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2014-01-02 16:54
I suggest that a documentation issue cannot be a release blocker. Most people read the documentation online, and will read an update once it is available.
msg207201 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-01-03 02:19
Agreed, this was set to ensure Larry followed up with a "Please explain" if
I didn't get it done in a timely manner.

I'll still try to get it done for the beta, but I still have
linux.conf.aupreparation to do, so it may slip to the first RC.
msg212928 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-03-08 12:46
After attempting to fix these docs in place, I now think that's a doomed effort. However, we can't just delete them, because they still contain details that haven't been moved to the distutils module docs or the Python Packaging User Guide yet.

So, what I'm planning to do instead is leave the existing Doc/install and Doc/distutils directories alone (including all their labels), changing the top level index page to point to new Doc/installing and Doc/distributing directories, and add a link to the old guides from the distutils docs page.

That will keep the legacy docs available, while removing all the confusing legacy cruft from the new end user facing docs (which can now just be very brief before redirecting to
msg212931 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-03-08 14:13
I like the way the attached patch has worked out - I think it's complete from a structural point of view.

The two missing pieces are to fill in the contents for the new Installing and Distributing guides, and those will be kept deliberately short, since we want to minimise the duplicating of content from the Python Packaging User Guide.
msg212943 - (view) Author: Marcus Smith (Marcus.Smith) (Python triager) Date: 2014-03-08 18:31
"Legacy version".  nice.   

btw, "" will certainly end up including "pyvenv" command examples as well.  currently just mentioned in a footnote.

like I mentioned on distutils-sig, I still hope to submit a patch to move critical content from the legacy pages to library/distutils.rst at some point.

also, btw, maybe you can fix this page real quick?  not sure what repo/team is managing this, but it's referencing the old HHGTP.
msg212946 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-03-08 23:37
Thanks for the feedback!

Could you lob that last one at the pythondotorg issue tracker on GitHub (
msg212947 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-03-08 23:44
And regarding moving the still-relevant content to the main distutils docs,
yeah that's still a good idea. However, that's going to take a fair bit
more work, since you'll need to evaluate the legacy content to decide what
needs preserving, and I don't know the technical details well enough to
make that call.

I figure the approach in my patch is a neat hack to move that task off the
Python 3.4 critical path, while still giving new Python 3.4 users a clean
and authoritative starting point for packaging issues :)
msg213118 - (view) Author: Marcus Smith (Marcus.Smith) (Python triager) Date: 2014-03-11 05:35
about the hhgtp link, logged here:  (and already fixed)

also, pyvenv is more prominent now in PUG as of latest changes (see
msg213199 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-12 05:36
Left some comments for Nick on Rietveld (the ever-useful CC name selection did not let me find you, so you may have not gotten a mail).
msg213388 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-13 12:14
New changeset d22ef969cb82 by Nick Coghlan in branch 'default':
Close #19407: New installation & distribution guides
msg213389 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-03-13 12:17
Not sure how much I'll be online tomorrow or Saturday, so I went ahead and committed what I had.

The new guides definitely aren't perfect, but I think they're in acceptable shape for 3.4.0, and we can improve them in parallel with Python Packaging User Guide updates (e.g. there were some "How do I...?" questions I left unanswered because the relevant PPUG sections don't have answers yet. In particular, I completely punted on the non-PyPI distribution question for now)
msg213391 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-13 12:33
New changeset f5be4ea5b43e by Nick Coghlan in branch 'default':
Issue #19407: fix link
msg213450 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-13 19:43
New changeset 25dc02a2acae by Ned Deily in branch 'default':
Issue #19407: Fix typos in new distribution & installation guides.
msg253897 - (view) Author: Jon Snoo (Jon Snoo) Date: 2015-11-02 07:34
The link to the "quick recommendations section" in the Python 2.7 and 3.3 docs is broken. It appears that the PPUG has changed the path from


Also, should the "Installing Python Modules" in Python 2.7.9 and 2.7.10 be the same as the one in Python 3.4? After all, pip is included in Python 2.7.9+, isn't it?
Date User Action Args
2022-04-11 14:57:52adminsetgithub: 63606
2015-11-02 07:34:28Jon Snoosetnosy: + Jon Snoo
messages: + msg253897
2014-03-13 19:43:21python-devsetmessages: + msg213450
2014-03-13 12:33:52python-devsetmessages: + msg213391
2014-03-13 12:17:17ncoghlansetmessages: + msg213389
2014-03-13 12:14:04python-devsetstatus: open -> closed
resolution: fixed
messages: + msg213388

stage: resolved
2014-03-12 05:36:15eric.araujosetmessages: + msg213199
2014-03-11 05:35:15Marcus.Smithsetmessages: + msg213118
2014-03-10 18:32:31eric.araujosetnosy: + eric.araujo
2014-03-08 23:44:33ncoghlansetmessages: + msg212947
2014-03-08 23:37:45ncoghlansetmessages: + msg212946
2014-03-08 18:31:28Marcus.Smithsetmessages: + msg212943
2014-03-08 14:13:25ncoghlansetfiles: + issue19407_packaging_docs.diff
keywords: + patch
messages: + msg212931
2014-03-08 12:46:01ncoghlansetnosy: + Marcus.Smith

messages: + msg212928
versions: - Python 2.7, Python 3.3
2014-01-03 05:20:09ncoghlanunlinkissue19347 dependencies
2014-01-03 05:15:20ncoghlansetpriority: release blocker -> deferred blocker
2014-01-03 02:19:56ncoghlansetmessages: + msg207201
2014-01-02 16:54:53loewissetnosy: + loewis
messages: + msg207175
2013-12-10 11:32:38python-devsetmessages: + msg205792
2013-12-10 11:19:25python-devsetnosy: + python-dev
messages: + msg205789
2013-12-10 10:49:50ncoghlansetpriority: deferred blocker -> release blocker

messages: + msg205786
2013-11-22 14:42:01ncoghlansetpriority: release blocker -> deferred blocker
2013-11-10 15:07:05ncoghlansetmessages: + msg202531
2013-10-30 14:18:35ncoghlansetmessages: + msg201737
2013-10-30 05:40:12ncoghlansetmessages: + msg201711
2013-10-28 12:59:02dstufftsetnosy: + dstufft
2013-10-26 12:49:16ncoghlansetmessages: - msg201346
2013-10-26 12:48:47ncoghlansetmessages: + msg201348
2013-10-26 12:48:16ncoghlansetmessages: + msg201346
2013-10-26 12:46:17ncoghlanlinkissue19347 dependencies
2013-10-26 12:45:27ncoghlansetdependencies: + PEP 453: add the ensurepip module
messages: + msg201344
2013-10-26 12:44:35ncoghlancreate