BUG: Failed to build Pandas 2.1.x Docs

[hwhsu1231]

Pandas version checks

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of pandas.

• I have confirmed this bug exists on the main branch of pandas.

Reproducible Example

# Prepare Environment
PANDAS_VERSION=2.1.x
git clone --branch=${PANDAS_VERSION} https://github.com/pandas-dev/pandas.git pandas-${PANDAS_VERSION}
cd pandas-${PANDAS_VERSION}
export LANG=en_US.UTF-8 LANGUAGE=en_US PYTHONNOUSERSITE=1
conda create --prefix ./.conda --yes
conda env update --prefix ./.conda --file environment.yml
conda activate ./.conda
pip uninstall pandas --yes
pip install --editable . --no-build-isolation --no-deps --progress-bar=off --verbose
conda list --export > env-pandas-${PANDAS_VERSION}.txt
cat env-pandas-${PANDAS_VERSION}.txt

# Build the Docs
python doc/make.py html
python doc/make.py clean
python doc/make.py html --num-jobs=1 --single user_guide/scale.rst

Issue Description

Hello, Pandas Community,

Recently, I tried to build the Pandas documentation on 2.1.x branch, but I encountered an error related to a missing directory when executing a code block in the user_guide/scale.rst file. The error message indicates that the directory data/timeseries does not exist, which causes a FileNotFoundError:

Click to expand the error message

(/media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.1.x/.conda) hwhsu1231@vb-kubuntu:/media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.1.x$ python doc/make.py html --num-jobs=1 --single user_guide/scale.rst
Running Sphinx v8.1.3
loading translations [en]... done
making output directory... done
Converting `source_suffix = ['.rst']` to `source_suffix = {'.rst': 'restructuredtext'}`.
[autosummary] generating autosummary for: index.rst
Writing evaluated template result to /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.1.x/doc/build/html/_static/nbsphinx-code-cells.css
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 2 source files that are out of date
updating environment: [new config] 2 added, 0 changed, 0 removed
WARNING: ources... [100%] user_guide/scale
>>>-------------------------------------------------------------------------
Exception in /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.1.x/doc/source/user_guide/scale.rst at block ending on line None
Specify :okexcept: as an option in the ipython:: block to suppress this message
---------------------------------------------------------------------------
FileNotFoundError                         Traceback (most recent call last)
Cell In[30], line 1
----> 1 pathlib.Path("data/timeseries").mkdir(exist_ok=True)

File /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.1.x/.conda/lib/python3.10/pathlib.py:1175, in Path.mkdir(self, mode, parents, exist_ok)
   1171 """
   1172 Create a new directory at this given path.
   1173 """
   1174 try:
-> 1175     self._accessor.mkdir(self, mode)
   1176 except FileNotFoundError:
   1177     if not parents or self.parent == self:

FileNotFoundError: [Errno 2] No such file or directory: 'data/timeseries'

<<<-------------------------------------------------------------------------

Exception occurred:
  File "/media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.1.x/.conda/lib/python3.10/site-packages/IPython/sphinxext/ipython_directive.py", line 585, in process_input
    raise RuntimeError(
RuntimeError: Unexpected exception in `/media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.1.x/doc/source/user_guide/scale.rst` line None
The full traceback has been saved in /tmp/sphinx-err-alx186om.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

The full log: log-build-pandas-2.1.x-docs.txt

But strangely, when I attempted to build the Pandas documentation on the 2.2.x, 2.3.x, and main branch, the build process completed successfully without any errors.

What happened between the 2.1.x and 2.2.x branches that resolved this issue? Is there a specific fix or change that was made to address this problem?

v2.2.3...v2.1.4

Expected Behavior

Build the documentation successfully without errors.

Installed Versions

INSTALLED VERSIONS
------------------
commit              : a671b5a8bf5dd13fb19f0e88edc679bc9e15c673
python              : 3.10.18.final.0
python-bits         : 64
OS                  : Linux
OS-release          : 6.8.0-79-generic
Version             : #79-Ubuntu SMP PREEMPT_DYNAMIC Tue Aug 12 14:42:46 UTC 2025
machine             : x86_64
processor           : x86_64
byteorder           : little
LC_ALL              : None
LANG                : en_US.UTF-8
LOCALE              : en_US.UTF-8

pandas              : 2.1.4
numpy               : 1.26.4
pytz                : 2025.2
dateutil            : 2.9.0.post0
setuptools          : 80.9.0
pip                 : 25.2
Cython              : 0.29.33
pytest              : 8.4.2
hypothesis          : 6.138.15
sphinx              : 8.1.3
blosc               : None
feather             : None
xlsxwriter          : 3.2.5
lxml.etree          : 6.0.1
html5lib            : 1.1
pymysql             : 1.4.6
psycopg2            : 2.9.10
jinja2              : 3.1.6
IPython             : 8.37.0
pandas_datareader   : None
bs4                 : 4.13.5
bottleneck          : 1.6.0
dataframe-api-compat: None
fastparquet         : 2024.11.0
fsspec              : 2025.9.0
gcsfs               : 2025.9.0
matplotlib          : 3.7.3
numba               : 0.61.2
numexpr             : 2.10.2
odfpy               : None
openpyxl            : 3.1.5
pandas_gbq          : None
pyarrow             : 21.0.0
pyreadstat          : 1.3.1
pyxlsb              : 1.0.10
s3fs                : 2025.9.0
scipy               : 1.15.2
sqlalchemy          : 2.0.43
tables              : 3.10.1
tabulate            : 0.9.0
xarray              : 2024.10.0
xlrd                : 2.0.2
zstandard           : 0.24.0
tzdata              : 2025.2
qtpy                : None
pyqt5               : None

[rhshadrach]

Thanks for the report. In case you weren't aware, the 2.1 docs can be accessed via the link below and downloaded as a zip file by the link on that page.

https://pandas.pydata.org/pandas-docs/version/2.1/index.html

Given that 2.1 is not going to see any more patches, especially not for documentation building, I do not think it would be worth spending any time identifying the cause here. Going to close for now. If you have a real use case where you need to build the 2.1 docs, state it here and we can reconsider.

[hwhsu1231]

Given that 2.1 is not going to see any more patches, especially not for documentation building, I do not think it would be worth spending any time identifying the cause here. Going to close for now. If you have a real use case where you need to build the 2.1 docs, state it here and we can reconsider.

Hello, @rhshadrach and other Pandas maintainers,

I am the author of @localizethedocs organization, which focuses on manufacturing the l10n projects of documentation for various open-source projects. Currently, I have estabalished an infrastructure to manufacture the l10n projects for those Sphinx-based documentations. For example:

• localizethedocs/cmake-docs-l10n
• localizethedocs/python-docs-l10n
• localizethedocs/ros2-docs-l10n
• localizethedocs/sphinx-docs-l10n

And currently, the pandas-docs-l10n project is in the incubation phase. During the process to incubate the l10n projects, the most important part is to make sure that the requirements are properly installed and the documentation can be built without any errors. If possible, I would like to maintain the .po files for different versions of the documentation, such as 1.5, 2.1, 2.2, 2.3, main,...,etc. However, I am encountering some errors when trying to build older versions of the Pandas documentation, and this issue is one of them.

I will appreciate it if the Pandas maintainers can help me resolve these issues and even fix them in the source code. For example, if the currently latest release tag of 2.1.x branch is v2.1.4, I hope the fix can be merged into 2.1.x branch and even tagged as v2.1.5.

---

I noticed that some issues are asking for the translation of Pandas documentation:

• About the internationalization of documentation #56301
• Translation of official documentation into Portuguese #39996

I believe my pandas-docs-l10n project can fulfill such needs. (once it's completed)

[rhshadrach]

Thanks for the context here. I'm happy to reopen, but I'm rather negative on releasing older versions of pandas, including only on GitHub. This also includes having the tags out of sync with the releases. I'd be okay with merging a patch to 2.1.x though.

cc @mroeschke for any thoughts.

[hwhsu1231]

One more thing to mention:

Pandas 2.0.x Docs can be built successfully with the following commands:

# Prepare Environment
PANDAS_VERSION=2.0.x
git clone --branch=${PANDAS_VERSION} https://github.com/pandas-dev/pandas.git pandas-${PANDAS_VERSION}
cd pandas-${PANDAS_VERSION}
export LANG=en_US.UTF-8 LANGUAGE=en_US PYTHONNOUSERSITE=1
conda create --prefix ./.conda --yes
conda env update --prefix ./.conda --file environment.yml
conda activate ./.conda
pip uninstall pandas --yes
pip install --editable . --no-build-isolation --no-deps --progress-bar=off --verbose
conda list --export > env-pandas-${PANDAS_VERSION}.txt
cat env-pandas-${PANDAS_VERSION}.txt

# Build the Docs
python doc/make.py html

although there are some warnings during the build process and kind of stalling in a point for a while:

Click to expand the warning messages

In file included from /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/.conda/lib/python3.8/site-packages/numpy/core/include/numpy/ndarraytypes.h:1940,
                 from /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/.conda/lib/python3.8/site-packages/numpy/core/include/numpy/ndarrayobject.h:12,
                 from /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/.conda/lib/python3.8/site-packages/numpy/core/include/numpy/arrayobject.h:5,
                 from /home/hwhsu1231/.cache/ipython/cython/_cython_magic_b8149f37d2d42c02ec4027a87b082e5a.c:769:
/media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/.conda/lib/python3.8/site-packages/numpy/core/include/numpy/npy_1_7_deprecated_api.h:17:2: warning: #warning "Using deprecated NumPy API, disable it with " "#define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION" [-Wcpp]
   17 | #warning "Using deprecated NumPy API, disable it with " \
      |  ^~~~~~~
In file included from /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/.conda/lib/python3.8/site-packages/numpy/core/include/numpy/ndarraytypes.h:1940,
                 from /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/.conda/lib/python3.8/site-packages/numpy/core/include/numpy/ndarrayobject.h:12,
                 from /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/.conda/lib/python3.8/site-packages/numpy/core/include/numpy/arrayobject.h:5,
                 from /home/hwhsu1231/.cache/ipython/cython/_cython_magic_07ac6b95fe730c890854f1ff3ac8496d.c:770:
/media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/.conda/lib/python3.8/site-packages/numpy/core/include/numpy/npy_1_7_deprecated_api.h:17:2: warning: #warning "Using deprecated NumPy API, disable it with " "#define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION" [-Wcpp]
   17 | #warning "Using deprecated NumPy API, disable it with " \
      |  ^~~~~~~
WARNING: 
>>>-------------------------------------------------------------------------
Warning in /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/doc/source/getting_started/intro_tutorials/04_plotting.rst at block ending on line 70
Specify :okwarning: as an option in the ipython:: block to suppress this message
----------------------------------------------------------------------------
<ipython-input-6-1eb00ff78cf2>:1: UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.
  plt.show()
<<<-------------------------------------------------------------------------
WARNING: 
>>>-------------------------------------------------------------------------
Warning in /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/doc/source/getting_started/intro_tutorials/04_plotting.rst at block ending on line 99
Specify :okwarning: as an option in the ipython:: block to suppress this message
----------------------------------------------------------------------------
<ipython-input-8-1eb00ff78cf2>:1: UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.
  plt.show()
<<<-------------------------------------------------------------------------
WARNING: 
>>>-------------------------------------------------------------------------
Warning in /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/doc/source/getting_started/intro_tutorials/04_plotting.rst at block ending on line 122
Specify :okwarning: as an option in the ipython:: block to suppress this message
----------------------------------------------------------------------------
<ipython-input-10-1eb00ff78cf2>:1: UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.
  plt.show()
<<<-------------------------------------------------------------------------
WARNING: 
>>>-------------------------------------------------------------------------
Warning in /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/doc/source/getting_started/intro_tutorials/04_plotting.rst at block ending on line 154
Specify :okwarning: as an option in the ipython:: block to suppress this message
----------------------------------------------------------------------------
<ipython-input-13-1eb00ff78cf2>:1: UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.
  plt.show()
<<<-------------------------------------------------------------------------
WARNING: 
>>>-------------------------------------------------------------------------
Warning in /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/doc/source/getting_started/intro_tutorials/04_plotting.rst at block ending on line 178
Specify :okwarning: as an option in the ipython:: block to suppress this message
----------------------------------------------------------------------------
<ipython-input-15-1eb00ff78cf2>:1: UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.
  plt.show()
<<<-------------------------------------------------------------------------
WARNING: 
>>>-------------------------------------------------------------------------
Warning in /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/doc/source/getting_started/intro_tutorials/04_plotting.rst at block ending on line 214
Specify :okwarning: as an option in the ipython:: block to suppress this message
----------------------------------------------------------------------------
<ipython-input-20-1eb00ff78cf2>:1: UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.
  plt.show()
<<<-------------------------------------------------------------------------
WARNING: 
>>>-------------------------------------------------------------------------
Warning in /media/hwhsu1231/KubuntuData/Repo/testing/pandas-2.0.x/doc/source/user_guide/10min.rst at block ending on line 756
Specify :okwarning: as an option in the ipython:: block to suppress this message
----------------------------------------------------------------------------
<ipython-input-137-993bc8a3a2a6>:1: UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.
  plt.show();
<<<-------------------------------------------------------------------------

The full log: log-build-pandas-2.0.x-docs.txt

[mroeschke]

It's not exactly clear that this is a specific pandas error since the error comes from Pathlib not being able to create a directory? Especially since it appears that snippet is the same across all the 2.x versions.

I am -0 pushing something to the 2.1.x branch specifically for this since it's not obviously pandas specific. Maybe your script can patch around this file for 2.1.x or try installing different Python or Sphinx versions to see if it's still happening.

Nonetheless, a future enhancement is that the line where this is failing should probably be using a temporary directory

[hwhsu1231]

Hello, @mroeschke

Maybe your script can patch around this file for 2.1.x or try installing different Python or Sphinx versions to see if it's still happening.

I've been trying to do this, but I'm still not able to build the 2.1.x docs successfully so far. I'd like to confirm something, though. Have you attempted to test the 2.1.x branch in your local environment using the commands I provided in the "Reproducible Example"? Were you able to reproduce the same error?