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.

classification
Title: 'Installing Python Modules' does not work for Windows
Type: enhancement Stage: resolved
Components: Documentation, Windows Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: BreamoreBoy, ajaksu2, docs@python, eric.araujo, jaraco, lambacck, python-dev, tautology, terry.reedy
Priority: normal Keywords: patch

Created on 2007-01-02 16:32 by tautology, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Messages (25)
msg61050 - (view) Author: Christopher Lambacher (tautology) Date: 2007-01-02 16:32
The instructions for installing 3rd party modules will not work in a default Windows install.

The documentation (http://docs.python.org/inst/standard-install.html) says:
"""
As described in section 1.2, building and installing a module distribution using the Distutils is usually one simple command:

python setup.py install

On Unix, you'd run this command from a shell prompt; on Windows, you have to open a command prompt window (``DOS box'') and do it there; on Mac OS X, you open a Terminal window to get a shell prompt.
"""

Unfortunately the command 'python setup.py install' does not work because the python executable is not in the path in the default install.  'setup.py install' will work since .py files are associated with python.exe.

A suggestion for new wording:
"""
As described in section 1.2, building and installing a module distribution using the Distutils is usually one simple command:

python setup.py install

On Unix, you'd run this command from a shell prompt; on Mac OS X, you open a Terminal window to get a shell prompt.

On Windows, you have to open a command prompt window (``DOS box'') and modify the command to:

setup.py install
"""
msg61051 - (view) Author: Christopher Lambacher (tautology) Date: 2007-01-02 16:36
Might as well also deal with section 1.2 as well.  http://docs.python.org/inst/trivial-install.html#new-standard says:
"""
Additionally, the distribution will contain a setup script setup.py, and a file named README.txt or possibly just README, which should explain that building and installing the module distribution is a simple matter of running

python setup.py install

If all these things are true, then you already know how to build and install the modules you've just downloaded: Run the command above. Unless you need to install things in a non-standard way or customize the build process, you don't really need this manual. Or rather, the above command is everything you need to get out of this manual. 
"""

Could be changed to:

"""
Additionally, the distribution will contain a setup script setup.py, and a file named README.txt or possibly just README, which should explain that building and installing the module distribution is a simple matter of running

python setup.py install

On Windows the above command should be modified to:

setup.py install

If all these things are true, then you already know how to build and install the modules you've just downloaded: Run the command above. Unless you need to install things in a non-standard way or customize the build process, you don't really need this manual. Or rather, the above command is everything you need to get out of this manual. 
"""
msg113640 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-08-11 22:47
My personal taste is that there is virtue in having such simple examples uncluttered by OS-specific variations, but since MvL does not want the python executable to be on the PATH per default, I defer to him and accept your solution. I’ll make a patch with a slightly different wording than the one you proposed.
msg137947 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-06-09 11:16
New changeset 2951641faed1 by Éric Araujo in branch '2.7':
Add examples that work on Windows to distutils docs (#1626300)
http://hg.python.org/cpython/rev/2951641faed1
msg137957 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-06-09 12:10
New changeset 072dbebaa83b by Éric Araujo in branch '3.2':
Add examples that work on Windows to distutils docs (#1626300)
http://hg.python.org/cpython/rev/072dbebaa83b
msg137963 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-09 12:28
This is now fixed in the distutils Installing and Distributing guides.  Does the same problem apply to the new docs using packaging and the pysetup script?  Please check http://docs.python.org/dev/packaging and http://docs.python.org/dev/install
msg140437 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-15 16:05
In distutils docs, I’ve mentioned “setup.py thing” as an alternative to “python setup.py thing” on Windows.  For packaging, the situation is different: there is no local script anymore, people will have to invoke the global pysetup command.  Would it work if I add a note like this:

  In order to run pysetup commands, you need to add the Python Scripts
  directory to your PATH *include link to relevant section of
  docs.python.org/using*.

BTW, do scripts work without file extensions, or does the installer add .py?  If it’s the latter, then my doc note will need to mention that too.
msg140452 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-07-15 18:36
On Windows, scripts run with whatever name -- no extension or other extensions. I have tested this from both IDLE and command line.
msg140577 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-18 13:46
> On Windows, scripts run with whatever name -- no extension or other
> extensions.
Thanks, this means that the docs can continue to say just “pysetup3”, without “.py”.

(I wonder how Windows manages to run the script without file extension!)

> I have tested this from both IDLE and command line.
You can run command-line scripts from IDLE?

Can you also comment on my proposed note about adding Scripts to PATH?
msg140593 - (view) Author: Chris Lambacher (lambacck) * Date: 2011-07-18 14:57
I don't think that is the default state. You need to add .py to the PATHEXT environment variable:
http://effbot.org/pyfaq/how-do-i-make-python-scripts-executable.htm

Maybe Terry did this at some point? My windows box certainly does not have it and I have 2.6 and 2.7 installed. I don't have a 3.x install so I can't check if that is new in 3.
msg140595 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-07-18 15:28
I perhaps misunderstood your question. I ran files from the command line as as 'python whatever', not 'whatever' so only python would care about an extension. I do not have a file association to 'run' a file, with or without .py. I presume IDLE does same when one RUNs a file, except with pythonw.
msg140596 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-18 15:39
The original bug is that the distutils docs use commands like “python setup.py spam” all over the place, and they don’t typically work
> because the python executable is not in the path in the default
> install.  'setup.py install' will work since .py files are associated
> with python.exe
(quoted from the first message).  I added a note to instruct Windows users to mentally replace those commands with “setup.py spam”.

Now my concern is about packaging: In a typical Windows install, can people run “pysetup3 spam”?
msg140604 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-07-18 17:08
I went back and reread from the beginning, instead of merely answering the question you asked when adding me as nosy. More comments:

Windows file associations are so disfunctional that you should not depend on them being anything in particular. I nearly always open files from within applications (IDLE for python files) or with RightClick context menu when an entry specifies the app that will be used (as with 'Edit with Notepad++' (getting Python make such is another issue). The only way I can run from Command Prompt is to cd to the appropriate pythonxy directory and enter 'python full\path\to\file' (with stupid backslashes or 'python -m module' (which looks for module under /Lib). 

In XP, and I presume later, the term 'DOS box' is obsolete and I would delete it. The 'Command Prompt' app (with caps) is found in the Start/Accessories directory. So I would say "open a Command Prompt window (in Start/Accessories)"

Back to your message where you added me. I am not sure of the difference between 'local script' and 'global command'. I do not understand your proposed note, especially "*include link to relevant section of docs.python.org/using*.".

Script run without extensions when run with an explicit python command.
I was primed to answer this because someone recently, on the tracker or python-list, proposed to 'fix' a problem (wrongly) by adding a .py(o/w) extension check to determine if a file is Python code before running it.

I am not sure what 'or does the installer add .py?' could mean. The Windows installer? 'Add' to what? 

I realize that my answers may appear naive. I hope usefully so. I have used Windows since Win95 and have learned to focus, as described above, on what dependably works with minimal surprise. The extremely few 3rd party Python-based stuff I have installed has either come as a zipped library I could extract into site-packeges or as an independent app to be unzipped elsewhere or installed with a Windows-style installer. I have never used setup.py so no expert advice on its successor from me.
msg140607 - (view) Author: Chris Lambacher (lambacck) * Date: 2011-07-18 17:21
> Now my concern is about packaging: In a typical Windows install, can people run “pysetup3 spam”?

The windows installer does not make any additions to the path so it is unlikely that "pysetup3 spam" will work.

There is http://www.python.org/dev/peps/pep-0397/ which addresses running scripts in a multi-version windows environment but I don't think that will help in this case. 

If you are running more than 1 version of windows there is simple statement that tells you how to install and have the install go to the right interpreter. You are almost best to have a shortcut that gives you a command prompt with the PATH variable correctly set to the desired python instance. That does not help the 2.x crowd or anyone before 3.3 :/
msg140609 - (view) Author: Chris Lambacher (lambacck) * Date: 2011-07-18 17:39
> I am not sure of the difference between 'local script' and 'global command'

local script is the setup.py (or for that matter any other script in an arbitrary place in the filesystem. Global command is referring to something installed in %PYTHONINSTALLDIR%\scripts i.e. it is an installed command. This one operates on a specific version instance of python. I for instance have c:\python26\scripts\easy_install.exe and c:\python27\script\easy_install.exe and each of those operates on their own particular version. Neither are in my path. The current state is that I have to either put one of the scripts directories in my path or run easy_install with the full path. My understanding is that pysetup is a replacement for easy_install that will come with 3.3.

> I am not sure what 'or does the installer add .py?' could mean. The Windows installer? 'Add' to what? 

I was referring .py being added to the PATHEXT evironment variable. I think it is safe to say that has not happened and is likely a bad idea.
msg141162 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-26 15:54
> Windows file associations are so disfunctional that you should not
> depend on them being anything in particular.

Ah.  Do you think I should revert the change I did for distutils docs to recommend running “setup.py spam”?  I followed the opinion of the original poster (first message).

> 'python -m module' (which looks for module under /Lib).
Not only under Lib, but along sys.path.

> In XP, and I presume later, the term 'DOS box' is obsolete and I
> would delete it. The 'Command Prompt' app (with caps) is found in
> the Start/Accessories directory. So I would say "open a Command
> Prompt window (in Start/Accessories)"
Thanks, I will change this term.  I won’t put the menu path however, it could change in any version.

> I am not sure of the difference between 'local script' and
> 'global command'.
Chris replied to that: local script is setup.py in a directory you probably just got from unzipping a file downloaded from PyPI, global command is pysetup3, installed alongside idle3, pydoc3 and others.

>> In order to run pysetup commands, you need to add the Python
>> Scripts directory to your PATH *include link to relevant section
>> of docs.python.org/using*.
> I do not understand your proposed note, especially "*include link to
> relevant section of docs.python.org/using*.".
The docs instruct to run pysetup commands, like “pysetup list” or “pysetup install Sphinx”.  On UNIX, the script will be available after install just like pydoc or idle.  On Windows, I don’t know.  The goal of my note was to tell people to add the Scripts directory to their PATH, so that they can run “pysetup list” and co.

The *insert* part meant:  At this place I will put a link to the “Using Python on...” docs, i.e. http://docs.python.org/using/windows#configuring-python (which explain how to edit PATH).

(Saying pysetup vs. pysetup3 is another unrelated doc bug.)

> Script run without extensions when run with an explicit python
> command.
Like “python.exe setup” when the file really is setup.py?  I’d never have guessed that.

> I am not sure what 'or does the installer add .py?' could mean.
Do the Windows installers for CPython found on python.org install idle, pydoc and other scripts as “pydoc” or “pydoc.py”?

> I realize that my answers may appear naive. I hope usefully so.
They’re very useful.

> I have used Windows since Win95 and have learned to focus, as
> described above, on what dependably works with minimal surprise.
This is a very useful standpoint.

> I have never used setup.py so no expert advice on its successor from
> me.
It’s okay, I added you because you can comment on how scripts and programs work, and review my English.
msg141166 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2011-07-26 16:14
> > Script run without extensions when run with an explicit python
> > command.
> Like “python.exe setup” when the file really is setup.py?  I’d
> never have guessed that.

No. Python.exe expects the full path. The only way to execute scripts without the extension is if PATHEXT specifies extension and you invoke the script itself, in which case the default handler (for that extension) will be invoked on that file.
msg141175 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-07-26 18:20
I believe I meant that 'python setup' works when the script is named 'setup'. Which is to say, python does not require scripts to have an extension, as someone had thought in writing a patch.
msg141176 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-07-26 18:27
I do not know why the msi installer *silently* fails to properly register extensions even when I leave that checked, or how common that it. I have never looked into the issue more because for development, I prefer to run from an IDLE window and be dumped into the shell after and have a chance to examine data and re-call functions. I will soon do an install on a new machine, so I will see what a true 'default' install looks like.
msg142427 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-08-19 12:25
New changeset 59f7bbe1236c by Éric Araujo in branch '3.2':
Remove obsolete term + indicate how to find the program (#1626300).
http://hg.python.org/cpython/rev/59f7bbe1236c

New changeset adaec1a0dd47 by Éric Araujo in branch '3.2':
Fix instance I missed in 59f7bbe1236c (#1626300)
http://hg.python.org/cpython/rev/adaec1a0dd47
msg142433 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-08-19 12:28
New changeset e9022dc7a411 by Éric Araujo in branch '2.7':
Remove obsolete term + indicate how to find the program (#1626300).
http://hg.python.org/cpython/rev/e9022dc7a411
msg142488 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-08-19 18:47
On my fresh install, double clicking *does* run the file as it should, but the window disappears immediately, erasing output and error tracebacks, unless one adds something like ``input("Hit Enter to quit") at the end of the script so the user can see any output.
msg187258 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2013-04-18 15:16
Is any more work needed on this issue or can it be closed?
msg187265 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-04-18 16:19
I consider it Éric's decision.
3.3 on Windows comes with the new py launcher. That might be incorporated into the docs if it has not. That might also be a separate issue.
msg187267 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-04-18 16:46
I consider documentation for the py launched a distinct issue.  The original complaint here was fixed, the part about packaging does not apply anymore, so I will close this.  If one of the changed instructions still does not work (e.g. “setup.py build” does not work), please reopen.
History
Date User Action Args
2022-04-11 14:56:21adminsetgithub: 44392
2013-04-18 16:46:44eric.araujosetstatus: open -> closed
resolution: fixed
messages: + msg187267

stage: needs patch -> resolved
2013-04-18 16:19:03terry.reedysetmessages: + msg187265
2013-04-18 15:16:07BreamoreBoysetnosy: + BreamoreBoy
messages: + msg187258
2011-08-19 18:47:29terry.reedysetmessages: + msg142488
2011-08-19 12:28:06python-devsetmessages: + msg142433
2011-08-19 12:25:09python-devsetmessages: + msg142427
2011-07-26 18:27:57terry.reedysetmessages: + msg141176
2011-07-26 18:20:02terry.reedysetmessages: + msg141175
2011-07-26 16:14:17jaracosetmessages: + msg141166
2011-07-26 15:56:20eric.araujosetnosy: + jaraco
2011-07-26 15:54:52eric.araujosetmessages: + msg141162
2011-07-18 17:39:34lambaccksetmessages: + msg140609
2011-07-18 17:21:05lambaccksetmessages: + msg140607
2011-07-18 17:08:58terry.reedysetmessages: + msg140604
2011-07-18 15:39:21eric.araujosetmessages: + msg140596
2011-07-18 15:28:17terry.reedysetmessages: + msg140595
2011-07-18 14:57:06lambaccksetnosy: + lambacck
messages: + msg140593
2011-07-18 13:46:11eric.araujosetmessages: + msg140577
2011-07-15 18:36:39terry.reedysetmessages: + msg140452
2011-07-15 16:05:42eric.araujosetnosy: + terry.reedy

messages: + msg140437
versions: + Python 3.3, - Python 3.1
2011-06-09 12:28:00eric.araujosetmessages: + msg137963
2011-06-09 12:10:57python-devsetmessages: + msg137957
2011-06-09 11:16:31python-devsetnosy: + python-dev
messages: + msg137947
2010-08-11 22:47:19eric.araujosetassignee: docs@python -> eric.araujo
messages: + msg113640
2010-08-10 22:18:19eric.araujosetnosy: + eric.araujo
2010-08-10 11:32:20floxsetassignee: docs@python

components: + Windows
nosy: + docs@python
2010-08-07 18:33:45terry.reedysetversions: - Python 2.6
2010-07-10 06:26:15terry.reedysetversions: + Python 2.7, Python 3.2
2009-03-30 18:32:26ajaksu2linkissue5608 dependencies
2009-03-30 18:25:24ajaksu2setversions: + Python 2.6, Python 3.1
nosy: + ajaksu2

keywords: + patch
type: enhancement
stage: needs patch
2007-01-02 16:32:33tautologycreate