Troubleshooting¶
Almost everyone hits a few of these at some point. Nothing here means you did something wrong — most are one-time setup quirks of Windows, Python, or git. Find the error message you’re seeing and apply the fix.
Tip
Read the last line of an error message first. Python prints the longest part (the “traceback”) above it, but the final line is the one that says what actually went wrong.
Command not found¶
'python' is not recognized as an internal or external command (Windows),
or python: command not found (macOS/Linux)
Windows almost always means the “Add python.exe to PATH” checkbox was missed during installation. Re-run the Python installer, choose Modify, and make sure that option is ticked. As a quick workaround, try
pyinstead ofpython.On macOS/Linux, use
python3rather thanpython.
pip: command not found
Use
python -m pip(Windows) orpython3 -m pip(macOS/Linux) instead of barepip— it does exactly the same thing but goes through the Python you just verified is working.
cookiecutter: command not found
It installed, but into a folder your terminal doesn’t search. Run it through Python instead:
python -m cookiecutter <template-url>
pytest: command not found
pytest isn’t installed in the environment you’re currently in. Check your prompt shows
(.venv), then install the test dependencies:pip install -e ".[test]"
image_magic: command not found
This command is created by installing your package, and only exists while the virtual environment it was installed into is active. Check your prompt shows
(.venv); if not, activate it (see Prerequisites). If it is active, re-runpip install -e .from your project folder.
error: externally-managed-environment¶
Seen on newer Linux distributions and Homebrew Python when running
pip install outside a virtual environment. The system is protecting its
own Python installation from being modified.
If you’re installing a project (anything with
-e .), you should be in a virtual environment anyway — create and activate one first, per Prerequisites.If you’re installing
cookiecutter, which deliberately lives outside any project, use:pip install --user cookiecutteror, if your system provides it,
pipx install cookiecutter.
Running scripts is disabled on this system¶
Windows/PowerShell only, when activating a virtual environment:
.venv\Scripts\Activate.ps1 cannot be loaded because running scripts is disabled on this system
This is a Windows security default. Allow it for the current terminal window only (it resets when you close the window, and doesn’t change any system-wide setting):
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
Then run the activate command again. Alternatively, use the Command Prompt
(cmd) instead of PowerShell and activate with .venv\Scripts\activate.bat,
or use Git Bash and source .venv/Scripts/activate.
*** Please tell me who you are¶
Git refuses to create a commit until it knows what name to record on it. Run these once (see Prerequisites):
git config --global user.name "Your Name"
git config --global user.email "your.name@campus.tu-berlin.de"
Permission denied (publickey)¶
Git can’t prove to GitLab who you are, so your push is refused.
Check your SSH key is set up and uploaded to GitLab (see Prerequisites), then test the connection directly:
ssh -T git@git.tu-berlin.deA working setup answers
Welcome to GitLab, @yourusername!. If it doesn’t, the key in GitLab’s Preferences → SSH Keys doesn’t match the one on your machine — re-copy the contents ofid_ed25519.puband add it again.Also check your remote uses the SSH address (
git@git.tu-berlin.de:...) and not the HTTPS one (https://git.tu-berlin.de/...). Check withgit remote -v; fix withgit remote set-url origin git@git.tu-berlin.de:group/project.git.
Push rejected (non-fast-forward)¶
! [rejected] main -> main (fetch first)Updates were rejected because the remote contains work that you do not have locally
The remote repository has commits yours doesn’t. For a brand-new project this almost always means the “Initialize repository with a README” checkbox was left ticked when you created the GitLab project, so the server made a commit before you pushed.
Easiest fix for a fresh project: delete the GitLab project and create it again with that checkbox unticked.
Otherwise, pull the remote’s commits first and then push:
git pull --rebase origin main git push origin main
ModuleNotFoundError: No module named '...'¶
Python can’t find the package you’re importing. In this workshop it’s almost always one of three things:
Your virtual environment isn’t active. Check for the
(.venv)prefix in your prompt.The package isn’t installed into it. Run
pip install -e .from your project folder (the one containingpyproject.toml).You’re in the wrong directory, so Python can’t see the package folder. Check with
pwd(macOS/Linux) orcd(Windows).
If the missing module is matplotlib or pytest, you installed the
package without its test dependencies — use pip install -e ".[test]".
no tests ran / collected 0 items¶
pytest ran but didn’t find anything to run.
Run
pytestfrom your project folder (the one containing bothtests/andpyproject.toml), not from insidetests/and not from your home folder.Test files must be named
test_*.pyand test functions must start withtest_. Anything else is invisible to pytest.
Sphinx: autodoc: failed to import function¶
Sphinx is trying to read a docstring out of your code, but can’t import your package to reach it.
Locally: activate your virtual environment and run
pip install -e ., then rebuild.On Read the Docs: the build server needs to install your package too — make sure your
.readthedocs.yamlincludes thepython: install:section shown in Part 3 Tasks.Also check the dotted path matches your actual package name — it’s
your_package_name.module.function, using the name you chose when generating the project.
Sphinx: document isn't included in any toctree¶
You created a new .rst page but didn’t list it in a toctree, so
there’s no way to navigate to it.
Add the filename (without the
.rstextension) to thetoctreeblock inindex.rst, indented to line up with the entries already there.
My Read the Docs build didn’t trigger¶
Pushing to GitLab only rebuilds your documentation if a webhook connects the two — RTD has no way to know you pushed otherwise.
Check you completed the webhook steps in Part 3 Tasks. You can always trigger a build by hand from your project’s RTD page (Builds → Build Version) to confirm the build itself works, which separates “the build is broken” from “the trigger is missing”.
I’m stuck in the Python interpreter¶
If your prompt looks like >>>, you’re inside Python, not your terminal —
shell commands like cd or pip won’t work there.
Type
exit()and press Enter. (Ctrl+Z then Enter also works on Windows; Ctrl+D on macOS/Linux.)
I committed files I shouldn’t have¶
Folders like .venv/, __pycache__/, .tox/ and *.egg-info/
don’t belong in git. Adding them to .gitignore stops future commits,
but doesn’t remove what’s already tracked:
git rm -r --cached .venv __pycache__
git commit -m "Stop tracking generated files"
The files stay on your disk; git just stops following them.