Repository navigation
Regression: venv virtual environments not providing pydoc #117871
Description
Bug report
Bug description:
I started a new python project today and naturally did this within a venv virtual environment. Hitting some frustration on not seeing any documentation on the web pages for the modules I was utilising I turned to pydoc, but it found nothing. On checking the actual installed files for the modules they did have docstrings.
python -m pydoc ... worked properly.
Upon checking which pydoc pointed out I was still using the system pydoc, which would of course have no knowledge of the venv library path in order to look inside it for relevant documentation.
I found #59362 from 2012, which claims to have address this, so this is clearly a regression, but I've no idea when it was introduced.
I'm doing all of this on a Debian bookwork 12.5 system which is up to date. I've rested using a pyenv installed Python 3.12.3. I also have no pydoc in <venv>/Scripts on Windows (with Python from python.org installers) venvs.
- Set up pyenv using latest from https://github.com/pyenv/pyenv.git
- Ensure it's active, i.e. setting PATH and PYENV_ROOT, then performing shell initialisation.
- pyenv install 3.12.3
- pyenv local 3.12.3 and confirm with which python and python --version that it's using it.
- python -m venv venv-no-pydoc
These are the contents:
15:27:36 0$ ls -al venv-no-pydoc/bin/
total 44
drwx------ 2 athan athan 4096 Apr 14 15:27 ./
drwx------ 5 athan athan 4096 Apr 14 15:27 ../
-rw-r--r-- 1 athan athan 9033 Apr 14 15:27 Activate.ps1
-rw-r--r-- 1 athan athan 2064 Apr 14 15:27 activate
-rw-r--r-- 1 athan athan 941 Apr 14 15:27 activate.csh
-rw-r--r-- 1 athan athan 2220 Apr 14 15:27 activate.fish
-rwxr-xr-x 1 athan athan 245 Apr 14 15:27 pip*
-rwxr-xr-x 1 athan athan 245 Apr 14 15:27 pip3*
-rwxr-xr-x 1 athan athan 245 Apr 14 15:27 pip3.12*
lrwxrwxrwx 1 athan athan 43 Apr 14 15:27 python -> /usr/local/pyenv/versions/3.12.3/bin/python*
lrwxrwxrwx 1 athan athan 6 Apr 14 15:27 python3 -> python*
lrwxrwxrwx 1 athan athan 6 Apr 14 15:27 python3.12 -> python*I've worked around the issue in my project venv by setting up .venv/bin/pydoc with contents:
#!/usr/local/src/fysh-geoip-country/maxmind-geoip-country/.venv/bin/python
# -*- coding: utf-8 -*-
import pydoc
import sys
sys.path.append('/usr/local/src/fysh-geoip-country/maxmind-geoip-country/.venv/lib')
if __name__ == '__main__':
pydoc.cli()Using the full path on the #! line is how the provided pip script is set up, so there's no reason that the same code that achieves that couldn't also include the sys.path.append(...) line, or other equivalent to ensure pydoc knows about the path.
CPython versions tested on:
3.12
Operating systems tested on:
Linux
Activity
Athanasius commented on Apr 14, 2024
Actually, that hacked together pydoc isn't always working either. Having looked at some of the code I fear that something is undoing the addition to sys.path.
It works if I .venv/bin/pydoc geoip2.errors, but not with plain pydoc geoip2.errors, despite which pydoc citing that venv path.
Athanasius commented on Apr 15, 2024
Someone else-net has pointed out pypa/virtualenv#265
Athanasius commented on Apr 15, 2024
A workaround is:
i.e. ensuring the #! line points to the venv python is sufficient, no need to mess with sys.path directly.
gaborbernat commented on Jun 5, 2026
This isn't a regression — the standalone pydoc script was removed deliberately in 3.4 (gh-62424, commit 61d003a8f14, 2013-06-30) with the rationale "it causes problems on Windows and adds no value over and above python -m pydoc." The script you remember (gh-59362, added 2012) was intentionally dropped a year later, so the behaviour has been the same since 3.4.
The supported way inside a venv is python -m pydoc. The one leftover is activate.csh, which still defines alias pydoc python -m pydoc from the separate csh-support change (gh-59622); that's a small inconsistency, but the deliberate position is to use python -m pydoc rather than ship a pydoc script. (virtualenv keeps a pydoc wrapper in its activators — a deliberate divergence, not something CPython regressed.)
Recommend closing as not-a-bug.