Running `pelican_quickstart` on Windows 11

[frankiezafe]

machine

• windows 11
• git + bash
• python 3.12.7

issue

After installing pelican via pip using regular py -m pip install "pelican[markdown]"', rebooting the machine and making sure lib is installed properly and listed by pip list, the command pelican-quickstart` keeps returning an error message:
bash: pelican-quickstart: command not found

i didn't find a mention on how to fix this issue in my context in the documentation

once this script executed, the next command pelican -r -l was not working either

py ~/AppData/Local/Programs/Python/Python312/Lib/site-packages/pelican/tools/pelican_themes.py --list

does not return anything even if ~\AppData\Local\Programs\Python\Python312\Lib\site-packages\pelican\themes contains 2 themes

quickfix

by running:

py ~/AppData/Local/Programs/Python/Python312/Lib/site-packages/pelican/tools/pelican_quickstart.py

the script execute normally in my local folder

and to preview:

py -m pelican -r -l

[tubajavedd]

Hi, I’m a first-time contributor. I can reproduce this on Windows 11 and would like to work on fixing the documentation for this issue. May I take this?

[justinmayer]

@minchinweb: As our resident Windows expert, do you have any insight regarding this issue?

[minchinweb]

@frankiezafe :

bash: [...]

Why are you using bash on Windows? I think this is the source of your problems. I also suspect that if you were to run pip directly (i.e. not py -m pip) on the same shell you would get the same issue.

---

Your install path suggests that you used the Windows Python installer. On Windows, Python will install "scripts" (such as pelican and pelican-quickstart) to a Scripts subfolder of your Python installation; I expect this is at ~\AppData\Local\Programs\Python\Python312\Scripts. (This folder will likely be called bin on Linux-y systems.)

These .exe files are "stub files" that allow Python scripts to be called from the command line.

This Script folder might be missing from (bash's) PATH, which would explain by py works but not pelican.

Suggestions:

1. On Windows, use PowerShell (i.e. the default terminal). You can also upgrade to PowerShell v7 through the Windows Store (recommended).
   • you might still need to ensure that the Script folder is on your PATH, but the installer should add it in it's default configuration.
2. If you need a Linux environment but are running a Windows machine, look into WSL (Windows Subsystem for Linux).

Git's bash is truly a marvel that it works at all, but unless you deeply understand both Windows and Linux/bash, you're likely to continue to run into issues like this; issues that will return few useful search hints online too.

---

@tubajavedd : Please feel free to propose a documentation update to help with this. At a high level, it should probably note:

1. If you're getting bash: <command name>: command not found on Windows, please use PowerShell or WSL instead.
2. If you're getting <command name>: The term '<command name>' is not recognized as a name of a cmdlet, function, script file, or executable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again. on PowerShell and Pelican is installed, you likely have a PATH issue.

In particular, bash isn't a supported shell on Windows (unless you want to become the resident expert...).