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 ``py`` instead of ``python``. On macOS/Linux, use ``python3`` rather than ``python``. ``pip: command not found`` Use ``python -m pip`` (Windows) or ``python3 -m pip`` (macOS/Linux) instead of bare ``pip`` — 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: .. code-block:: none python -m cookiecutter ``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: .. code-block:: none 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 :doc:`prerequisites`). If it is active, re-run ``pip 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 :doc:`prerequisites`. If you're installing ``cookiecutter``, which deliberately lives outside any project, use: .. code-block:: none pip install --user cookiecutter or, 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): .. code-block:: none 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 :doc:`prerequisites`): .. code-block:: none 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 :doc:`prerequisites`), then test the connection directly: .. code-block:: none ssh -T git@git.tu-berlin.de A 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 of ``id_ed25519.pub`` and 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 with ``git remote -v``; fix with ``git 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: .. code-block:: none 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 containing ``pyproject.toml``). * **You're in the wrong directory**, so Python can't see the package folder. Check with ``pwd`` (macOS/Linux) or ``cd`` (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 ``pytest`` from your **project folder** (the one containing both ``tests/`` and ``pyproject.toml``), not from inside ``tests/`` and not from your home folder. * Test *files* must be named ``test_*.py`` and test *functions* must start with ``test_``. 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.yaml`` includes the ``python: install:`` section shown in :doc:`part3-documentation/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 ``.rst`` extension) to the ``toctree`` block in ``index.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 :doc:`part3-documentation/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: .. code-block:: none git rm -r --cached .venv __pycache__ git commit -m "Stop tracking generated files" The files stay on your disk; git just stops following them.