Opened 8 years ago

Closed 8 years ago

#4296 closed (fixed)

PYTHONPATH in mod_python documentation confuses almost everybody

Reported by: anonymous Owned by: jacob
Component: Documentation Version: master
Severity: Keywords: mod python, pythonpath
Cc: dev@…, knutin@…, Graham.Dumpleton@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: UI/UX:


It says:

PythonPath "path/to/project? + sys.path"

But if you SetEnv DJANGO_SETTINGS_MODULE project.settings, it throws this error:

EnvironmentError: Could not import settings 'project.settings-vatle.midgard' (Is it on sys.path? Does it have syntax errors?): No module named project.settings-vatle.midgard

The docs should say that the PythonPath should be the path to the parent dir of your project.

I don't know if this makes much sense, I'm new to django and python. It caused me some head-aches, but someone very helpful at #django pointed me in the right directon.

Thanks for all the great work!

Attachments (2)

django-modpython.diff (1.1 KB) - added by knutin@… 8 years ago.
Patch to docs/modpython.txt
modpython.diff (585 bytes) - added by Simon G. <dev@…> 8 years ago.

Download all attachments as: .zip

Change History (14)

comment:1 Changed 8 years ago by knutin@…

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

Forgot my email:



comment:2 Changed 8 years ago by SmileyChris

  • Cc knutin@… added
  • Triage Stage changed from Unreviewed to Accepted

comment:3 Changed 8 years ago by SmileyChris

Thanks for the report. You're right, this should be mentioned.

If you feel up to it, why not try your hand at providing a patch? Ask on #django if you need help with this.

Changed 8 years ago by knutin@…

Patch to docs/modpython.txt

comment:4 Changed 8 years ago by jacob

  • Resolution set to duplicate
  • Status changed from new to closed

Fixed; this is a dup of #3842.

comment:5 Changed 8 years ago by knutin@…

  • Has patch set
  • Resolution duplicate deleted
  • Status changed from closed to reopened

This is not a dup of #3842.

The patch I uploaded was applied and the problem this ticket adressed, got solved.

With your latest change, the text that caused problems got changed back to the original state before my patch.

The problem as stated in the ticket description, is that

PythonPath "['/path/to/project] + sys.path" 

tricks those new to django and python into thinking they have to use the path to their project, and *not* the parent dir as it should be:

PythonPath "['/your/python/path'] + sys.path"

Please have a look at the patch that I attached. I hope you will merge these changes.

comment:6 Changed 8 years ago by anonymous

Just chiming in that we get this sort of question on IRC all the time. While I don't think "/your/python/path" is any less confusing (it's already called PythonPath!), there should definitely be a note explicitly saying that the PythonPath should point to the parent directory of the project.

comment:7 Changed 8 years ago by Graham.Dumpleton@…

There is more wrong with the descriptions in the mod_python setup page than you think. Although the parent directory is always required to allow settings file to be picked up, in some cases the site directory also needs to be added to PythonPath. For an analysis of this see Django user list discussion at:

Thus, not just a simple case of changing what example path is shown as explanation of when to set PythonPath to needs to be changed as well as example of what it is set to.

comment:8 Changed 8 years ago by anonymous

  • Cc Graham.Dumpleton@… added

I agree with Graham that if the set of circumstances is known that causes the "two entries in PythonPath" problem to arise that it should be documented (or Django should automagically work around it). I'd also like to see a 'real world' example of setting PythonPath since neither /path/to/project nor /your/python/path make it clear to me actually what I'm trying to achieve. I think explicitly making reference to the ViewDoesNotExist exception and using the "two entries" technique to solve it would also reduce the overall quantity of pain and suffering in the world.

Sadly I am new to both Django and Python and don't really feel I can contribute a better solution. I'm trying to get better :)

Changed 8 years ago by Simon G. <dev@…>

comment:9 Changed 8 years ago by Simon G. <dev@…>

  • Cc dev@… added
  • Summary changed from Wrong path in mod_python documentation to PYTHONPATH in mod_python documentation confuses almost everybody

This still seems to be confusing people (#5004 was a dupe). I've attached an updated patch - can other people (Graham?, knutin@..?) check this and see if there's anything else to add here.

comment:10 Changed 8 years ago by Simon G. <dev@…>

  • Patch needs improvement set

comment:11 Changed 8 years ago by Paul Bx <pb@…>

Patch looks good. I'd change "should be" to "should include", since $PYTHONPATH often (as in the example) includes more than one directory.

People are still tripping over this. I think it's better to get this (much improved) wording into the docs than to succumb to a bikeshed discussion about the fine points. It can always be expanded later but this takes care of the most common point of confusion.

comment:12 Changed 8 years ago by mtredinnick

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

(In [5896]) Fixed #4296 -- Added more explanation around the PythonPath directory setting. Based on contributions from a cast of thousands (Simon Greenhill, Paul Bissex, Graham Dumpleton, ...). Thanks, all.

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