Change needed for pip - Django installation documentation

I am running Win 11 and just installed Python / Django with a lot of expert help because PIP was not installed on my PATHS automatically.

Further, the string to run PIP had to be setup with quote marks as such, or it wouldn’t run: “C:\Users\myAcctName\AppData\Local\Programs\Python\Python312\python.exe” -m pip install django

Last, I had to use the command prompt to add this information to my path as Windows GUI did not let me do it.

It would also help if prior to startup, I was given information as to what directory was required to run the PIP.

I’d be happy to report this to whomever would want to consider the issue. Can anyone tell me where user reports should go

The Python installer should have included the Python Launcher py, so this should work:

py -m pip install django

There were some problems on how to proceed for a person like myself, alone and not sitting with a development team. More information needs to be included. One of those problems is that the PATH was not addressed. My system rejected all mention of “py -m pip install django”

I don’t want to start an argument, but a bit more description and recognition of possible errors would be welcome on a new installation.

The issue is that all of the things that need to be explained here, are on the topic of how the command line works, how Windows paths work, etc. It’s certainly nothing specific to installing Django. The Pip documentation already explains some things about using Python explicitly to run Pip (as opposed to using pip directly as a command); but it’s assumed that you know how to use the command line and tell it which Python to use - because there are many ways to do that, and no piece of documentation can know how your system is configured.

This isn’t “the string to run Pip”. The part inside the quote marks is the path to Python; that would be the same if you were running Pip or any other module, or using the interactive interpreter (sometimes called REPL), or running your own source code file. It has nothing to do with Pip and nothing to do with Django.

If you needed to give a path like that, then yes, it’s because Python was not added to your PATH environment variable. (This is deliberately not done by default on Windows, for carefully considered reasons.)

If py didn’t work, that’s presumably because it wasn’t installed. (When the Python installer installs the py program, it goes directly into a Windows system folder - exactly to make sure that it will be found.) But “My system rejected all mention of “py -m pip install django”” is not a problem description that we can make any use out of. Error messages are displayed for a reason; please include them when describing a problem.

If you needed quotes around the explicit path, that’s because there’s a space in it somewhere (perhaps in your system username). This is an issue with Windows, that is very well covered by Windows and/or DOS documentation.

If you tried to add that path to PATH and it didn’t work, that’s again a Windows or DOS support issue; see for example:

More generally, issues related to using Python on Windows are covered in the Python documentation here:

You should also make sure you understand exactly what versions, and how many, are installed on your system. Normally, a Windows machine won’t have any version of Python pre-loaded. But it’s not hard to have installed a different version earlier and forgotten about it; or used the Windows Store promotional thingy to install a separate copy. There’s not a lot that Python can do to anticipate that, because it’s useful and normally intentional. But you need to be aware that every Python installation keeps its own set of third-party libraries such as Django; and uses its own separate copy of Pip to install those:

1 Like

I am not posing an argument, and perhaps my comment should be made in a Django user group. I am doing my “help the community thing” by bringing it up because the topic is fresh on my mind.

You have nothing to defend.

First-time users have a unique contribution to make to “getting started” documentation. I’m not sure whether it was Python or Django documentation you found unhelpful. The Python project tries to be supportive of anyone willing to contribute, and a documentation change is a good place to start.

The difficulty with installation and launching is that everyone’s environment seems to be broken in a different way as a result of their own workarounds and earlier installations. It is difficult for even an experienced developer to write the guide.

I have several different versions and implementations of Python installed and switch between them so I have a complicated PowerShell script that manipulates PATH and a few other variables.

It shouldn’t be that difficult to launch CPython. Something like @MRAB showed ought to work, using py or python as the command.

That’s surprising. On Windows there are two levels of environment-setting. (Go to “Settings” and search for “env”.) The first level affects all users and requires an admin log-in, but the second only affects you and is user-configurable (normally). It doesn’t take effect until you start a new command window.


Issues · python/cpython · GitHub for CPython and its docs, or if your issue is with Django or pip, somewhere similar you could find from the projects’ websites.

This is also usually where you could offer to fix it (a pull request) but start with an issue because you don’t necessarily have the best answer immediately.

Thanks, Jeff. Good answer.

I don’t think Karl was trying to argue or take a defensive stance, though I can understand how it might look that way. It’s just that there’s so much ground to cover for new users, it’s often difficult for us to know where to start.
I agree with Jeff that you have a valuable perspective to offer here – you only see something for the first time once – so I want us to make the best possible use of your experience!

Some of what you’re reporting looks like unfamiliarity with the command line and the PATH. It’s not specifically Python related – the same information would be important to learn if you were learning to use several other programming languages like Go, Rust, or Ruby.

That doesn’t mean it’s not in scope for Python docs. The docs have some responsibility towards new users to get you up and running. But it does make it very easy for doc authors to assume that you have the relevant background – they’ve been immersed in the space for years and mostly interact with others with a somewhat similar background.

It would be really helpful to know what docs you were looking at in this process. You mentioned “expert help”, but it sounds like you might have tried to do things on your own first. Where did you start? What docs or guidance were you following to install Python?
Whatever you can recall about this would be a big help. That’s where we may want to make adjustments.


I found out what the problem was. Note that I do understand command prompts (which old school, I refer to as DOS) and path statements. The problem for me, the new user of PYTHON, was missing a small checkbox during installation. The checkbox asks if I wanted to register its path.

Problem 1 was that the checkbox in the lower left part of the install screen is hardly noticeable, at least not by me. As a matter of fact, I only noticed it later via a video by Mosh Hamedani.

Problem 2 was that while I am used to DOS, I am not used to Windows’ setup windows as I’ve never had to use them before (and I’ve been using PCs since the 1970s). Consequently, I did not completely understand the variable form, felt uneasy, so reverted to something I did know - setting up the path in DOS. I thought that that might be a bit obscure to a new user, and that is what I posted here.

So, my recommendation is that the introductory Python screen should put the path option in a more prominent place and pair it with a description OR have it as an opt out.

Thanks for all the comments. I’m happily becoming acquainted with Python now and look forward to mastering it.



First, my apologies. Terminology is hard, and often not suited to casual discussion; and it seems this led me to misjudge your experience greatly. (Reading tone is also hard; for what it’s worth I only intended to be matter-of-fact, and likewise I didn’t perceive any particular annoyance from you.)

Adding Python to the PATH variable manually in DOS certainly resolves the issue. However, in the OP you mentioned that “Windows GUI did not let me” modify the path, which is noteworthy. I can’t think of any reason why that would ever fail, done properly; but there is a common oversight people make when trying to use the GUI for this - it doesn’t affect already-open terminal windows:

(The same can happen with the installer, but people usually don’t notice because they wouldn’t have a terminal window already open while running the installer.)

As for the installer itself, nowadays (and for many years) Windows developers have been more or less expected to create installers if there are any meaningful setup steps (i.e. any reason why the program can’t just be dropped in some arbitrary place and double-clicked to execute). It’s generally expected that setup can also be modified by using the OS-level “Programs and Features” UI, which will re-run the installer (I’m not clear on whether it passes a special flag to the installer program or just what). To my understanding, this is supposed to work for the Python installer, including for the PATH setting - i.e., you can “modify” the installation, check or un-check the box, and PATH should be re-adjusted as appropriate. But aside from some general conventions, every application developer is on their own to design the installer - because every program has potentially unique requirements for setup.

I agree that the option should be more prominent, and given some appropriate discussion, because it’s unusual for installers to do this. Almost everything installed on Windows will happily add itself to PATH if it deems that necessary (for example, because multiple executables are installed that need to communicate by script) without considering any potential consequences. After all, ordinary programs are meant for ordinary users - who may never open a CMD window unless being directly hand-held through the process by a support technician.

My best guess is that the goal was to avoid intimidating those exact users - since Python is certainly perfectly usable by only ever installing a single version, only ever editing the scripts in IDLE (opened by double-clicking a Desktop shortcut), and perhaps running the scripts by double-clicking them (which depends on a file association in the Registry, not on the PATH setting). However, we do get a lot of questions related to the PATH setting here - including the issue you describe. But programmers in the long run need to understand how PATH works, as part of understanding how file paths work - along with relative vs. absolute paths, etc. (As computers - and now cell phones - become more “user friendly”, people have been losing that knowledge; so nowadays, new programmers may ask questions that even ordinary computer users would have been able to answer many years ago.)

I also agree that there should be some explanation written there - but I can’t really think of exactly what it should say. Hyperlinking to the “Using Python on WIndows” documentation would be a good start, at least.

But there are good reasons why the PATH modification is opt-in - here’s some previous discussion from late 2020, for example:

The core underlying issue is that Windows wants each application to have a separate subfolder within Program Files for the .exe along with any support files that are particular to that program (for Python, that would include things like the standard library source code). So, each new application needs a new PATH entry in order to be found that way. On UNIX-like systems, the actual executable applications are normally side-by-side in /usr/bin (or /usr/local/bin etc.), while any supporting, non-executable files are in a subfolder of /usr/lib (or /usr/local/lib etc.). With that setup, running python (or python3, python3.12 etc.) doesn’t require separate PATH entries - because they all use the same one, which is already there by default.

Well, blame my sloppy description on the fact that I am 80, retired 10 years ago, and have been out of the programming environment for maybe 15 years. My objective is to learn Python, which does not seem all that hard, for personal and grandiose projects that Microsoft might buy.

I have never tended a web server or a server of any type in my life. The companies I worked for always separated personnel functions. The result of that was my fumbling, which older person, I am used to. Prior to my recent experience with Window’s system variables, I’ve never touched any of its setup forms and frankly, did not fully understand how the form worked. I now understand it, but if ignorance really troubled me, I would have never gotten Python installed and I wouldn’t be using it now.

My approach to programming is in true pythonesque fashion. I might look like an idiot from time to time, but ultimately, I get the job done.

I’ve written hundreds of pages of user guides and documentation, as well as illustrated concepts. I have written programs that controlled large corporate departments. On the fateful night I installed Python on my machine, however, I had no programming buddies to ask, so just did what I knew and did not blow up my PC. If a grandma can’t be a cowboy, what is life worth?

Now, about that installation screen, there must be others like me who want to learn, are not system engineers, and who have no programming buddies to ask for help during installation so however muddled, I think my bringing up the subject has merit.

My advice for that installation screen: The checkbox should be prominent and explained. For an individual computer, check it. For a network, consult your network supervisor as it can be added later.

1 Like

Awesome. :cowboy_hat_face: Teach the grand-kids to ride too.