Working on Windows¶
Jupyter Book is now also tested against a Windows environment on Python 3.7 😀
For its specification, see the
windows-latest runner used by GitHub CI.
However, there is a known incompatibility for notebook execution, when using Python 3.8 (see issue #906).
If you’re running a recent version of Windows 10 and encounter any issues, you may also wish to try installing Windows Subsystem for Linux.
As of June 5, 2020, there were three open issues that required Windows-specific changes. We hope these are now fixed in version 0.8 of Jupyter Book but, in case any issues still arise, we leave these community tips, which are known to work for some users. Note that there is no guarantee that they will work on all Windows installations.
Jupyter Book currently reads and writes files on Windows in the native Windows encoding, which causes encoding errors for some characters in UTF8 encoded notebooks.
Work-around: Beginning with Python 3.7 cmd.exe or powershell enviroments that set PYTHONUTF8=1 override the native locale encoding and use UTF8 for all input/output.
A new Windows event loop
The asyncio event loop has been changed for Python 3.8 causing sphinx-build to fail.
Work-around: Pin to Python 3.7.6. This environment_win.yml file does that, and also installs runjb to fix issue 1.
Nested tables of contents
_toc.ymlfiles that reference Markdown files in sub-folders are failing for some Windows users. That is, this original _toc.yml file will fail with a message saying Jupyter Book “
cannot find index.md”
Work-around: Flatten the layout of the book to a single level, i.e. this _toc.yml file works with Windows.
The following workflow should succeed using a miniconda powershell terminal on Windows 10:
conda install git
git clone https://github.com/eoas-ubc/quantecon-mini-example.git
git checkout windows
conda env create -f environment_win.yml
conda activate wintest
After the build, view the HTML with: