Opened 4 years ago

Closed 17 months ago

Last modified 17 months ago

#16205 closed New feature (fixed)

Beginners install guide for Windows

Reported by: erlingbo Owned by: anubhav9042
Component: Documentation Version: master
Severity: Normal Keywords: install, windows
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

When people are completely new to Python and Django there are often easy to stumble upon certain show stoppers making the interest fade away.

When people are attending basic tutorials or classes, there should be an easy way to get Django installed as fast as possible. This is not well documented for the Windows platform.

Documentation on how to get a basic Django environment running on Windows is included as a rst file. I have not made a lot of thoughts of where in the documentation this should be included. Maybe as a topic? Or in intro?

Comments and improvements are more than welcome.

Attachments (2)

install-windows.txt (3.4 KB) - added by erlingbo 4 years ago.
Beginners install guide for Windows
16205.diff (4.4 KB) - added by melinath 4 years ago.

Download all attachments as: .zip

Change History (19)

Changed 4 years ago by erlingbo

Beginners install guide for Windows

comment:1 Changed 4 years ago by aaugustin

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement set
  • Triage Stage changed from Unreviewed to Accepted

Setting "patch needs improvement" because the attachement is not actually a patch. This file must be added in docs, and linked to from other pages.

IMO https://docs.djangoproject.com/en/dev/topics/install/ is an appropriate entry point.

comment:2 Changed 4 years ago by melinath

  • Owner changed from nobody to melinath
  • Status changed from new to assigned

Going to make this a patch.

Changed 4 years ago by melinath

comment:3 Changed 4 years ago by melinath

  • Owner melinath deleted
  • Status changed from assigned to new

I ended up putting the tutorial in /howto/windows, parallel to /howto/jython, since it is a howto with a specific target audience rather than an exhaustive guide. However, I think that it still needs work. I would have tried, but I don't really use windows much. Things that I think need to be fixed:

  1. the guide installs easy_install *and* pip. Shouldn't easy_install be enough? Having both will probably confuse beginners who just want to get things installed.
  2. the guide assumes that the users have administrative access and want to use it in combination with a shell. On linux, easy_install has a --user option which installs to the user's directory (thus avoiding the need for admin access) - isn't there a similar option on windows?
  3. There is only one pitfall in "Common pitfalls" - perhaps rename the section? Also, what's the policy on linking to stackoverflow answers from django docs?

comment:4 Changed 4 years ago by erlingbo

I see your point about both easy_install and pip. Though, I thought PIP was starting to be the defacto package manager, and do we then want to let beginners start using (and learning) easy_install? Installing PIP is not a hard nor time consuming task.

I am not aware of such an option at least. And I could not find such an option in the basic help for either easy_install nor pip. I do not normally develop on Windows, and maybe I didn't look good enough.

The 'Common pitfalls' sections was/is supposed to be bigger. There are probably more things that can go wrong. We are working with a guide for Windows, right? ;)

Regarding the policy of linking to Stackoverflow, I do not know what the policy is. Someone else will have to answer on that one. If that is not ok, we will have to include the whole solution into this guide.

comment:5 follow-up: Changed 4 years ago by mtredinnick

A couple of comments based on reading about a billion emails from Windows people making all kinds of errors:

  1. This needs to be tested on a few different versions of Windows. Unsurprisingly, not everybody runs the latest version. The documentation needs to mention which versions the instructions are for. At a minimum, I would think Windows 7 and Vista are needed.
  1. Prefer pip as much as possible (although to bootstrap it, you need easy-install). It is a much better habit to get into.
  1. Try to write the instructions so that they work for non-admin users if at all possible.
  1. Find some willing friends, colleagues, people who owe you something, mailing list compadres, ... anybody you can to test it from a clean slate. It took us a lot of attempts to even get the instructions correct for how to make "python django-admin.py" work correctly across multiple Windows versions in earlier documentation. There is a distinct lack of consistency (or sanity) involved.

comment:6 in reply to: ↑ 5 Changed 4 years ago by jezdez

Replying to mtredinnick:

  1. Prefer pip as much as possible (although to bootstrap it, you need easy-install). It is a much better habit to get into.

I agree pip should be preferred, but easy_install isn't needed actually. setuptools (or its better sibling Distribute) is needed though (which also contain easy_install, but that's not important).

See http://www.pip-installer.org/en/latest/installing.html for installing/upgrading instructions, especially the bootstrapper called get-pip.py (which internally is pip itself).

comment:7 Changed 3 years ago by timo

See also #18410 for possible issues when installing on Windows.

comment:8 Changed 3 years ago by manfre

  • Owner set to manfre
  • Status changed from new to assigned

I'll work on the documentation. My job wants me to update our internal wiki's "Setting up a developer laptop" page, which has a large section on getting up and running with Django.

comment:9 Changed 18 months ago by anubhav9042

I am thinking to work on this.
I use django with windows. I know how to setup django environment on windows. I think along with "beginner guide" we should also add how to setup django development environment(for contribution) on windows, especially running test suite with virtualenv.

If someone is already working on this, please reply.

comment:10 Changed 18 months ago by manfre

  • Owner manfre deleted
  • Status changed from assigned to new

comment:11 Changed 18 months ago by anubhav9042

  • Owner set to anubhav9042
  • Status changed from new to assigned

comment:12 Changed 18 months ago by anubhav9042

I want to make sure what we are aiming for:

Make a separate howto for installing on windows and incorporate relevant details in install page also.
I will include the following steps:

1)Install python using MSI installer. Setting up Environment variables(if not set as in some cases in Windows 8)
2)Install setuptools using its setup file(ez_setup.py) or if your windows has a powershell(as in Windows 8 onwards) there is a direct way.
3)Install django using easy_install django or download source and unzip install using python setup.py install
4)For database eg.MySQL install MySQL then its python connector.
5)Relevant links to source pkg pages will be there.

We also need to add how to run test suite on windows in development environment using virtualenv.(We could include that in this as well.)

Well I prefer easy_install over pip.
Reasons for it:

  • pip has some problem when installing behind proxy even when env var have been set, easy_install works smoothely.
  • Also easy_install gives a much better progress display. eg. If some dependancy could not be installed it gives the url which it could not fetch we could go there in the browser and manually download source pkg and install using python setup.py install.

Any changes required?

comment:14 Changed 18 months ago by anubhav9042

  • Patch needs improvement unset

comment:15 Changed 17 months ago by Tim Graham <timograham@…>

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

In d35d2f61c595fc9e6a03cfcbc21a4d5f937e3633:

Fixed #16205 -- Added an installation for Windows.

comment:16 Changed 17 months ago by Tim Graham <timograham@…>

In 23526d2f483a893414884a154a10c0c43bcd0689:

[1.6.x] Fixed #16205 -- Added an installation for Windows.

Backport of d35d2f61c5 from master

comment:17 Changed 17 months ago by Tim Graham <timograham@…>

In 2cb70131790d5455b94d640e0f6838434b64e39b:

[1.7.x] Fixed #16205 -- Added an installation for Windows.

Backport of d35d2f61c5 from master

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