Chapter 2 walks you through installing Python and VS Code. This appendix collects the problems people run into afterwards, in one place, sorted by what you see.

#First, three quick checks

Most setup problems are solved by one of these. Try them in order before anything else:

Close and reopen. Close every terminal window, and close VS Code completely. A terminal only reads the PATH when it starts, and VS Code only notices a newly installed Python when it starts.
Check which Python you’re using. In a terminal, run python --version (Windows) or python3 --version (Mac and Linux). In VS Code, look at the right-hand end of the status bar at the bottom.
Check where you are. Run cd (Windows) or pwd (Mac and Linux) to see which folder the terminal is in. Your script needs to be in that folder, or you need to give its full path.

#Windows

python isn’t recognised, or the Microsoft Store opens. Try py --version. If that works, use py wherever this book says python. If not, Python isn’t on the PATH. If you used the traditional installer, run it again, choose Modify, click Next, and tick Add Python to environment variables. If you used the install manager, search the Start menu for Manage app execution aliases and make sure the Python entries are switched on. Then close and reopen the terminal.

You have more than one Python. Run py --list to see them all. Pick one in VS Code with Python: Select Interpreter, and use the same one in the terminal. Having two isn’t a problem in itself; using one for pip install and the other to run your code is.

PowerShell says running scripts is disabled. This happens when you activate a virtual environment in PowerShell, which is VS Code’s usual terminal on Windows. Either switch to Command Prompt (click the small arrow next to the + in VS Code’s terminal panel and choose Command Prompt), or allow scripts for your own account by running this once in PowerShell:

Terminal

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Your file is called hello.py.txt. Windows hides file extensions by default. In File Explorer choose View > Show > File name extensions (on Windows 10, the View tab, then File name extensions), and rename the file.

Environment variables (like SMTP_USER) aren’t seen by your script. In PowerShell, set them with $env:SMTP_USER = "you@example.com". In Command Prompt, use set SMTP_USER=you@example.com, with no spaces around the =. Either way, they last only until you close that terminal.

#macOS

python: command not found. Use python3. On a Mac, python on its own usually doesn’t exist.

A box asks to install “command line developer tools”. You’ve run the Mac’s old placeholder python3, not the one from python.org. Close every Terminal window and open a new one. If the box still appears, it’s safe to install the tools.

CERTIFICATE_VERIFY_FAILED when downloading. Open Applications, then the Python 3.x folder, and double-click Install Certificates.command.

error: externally-managed-environment from pip. This happens with Python installed by Homebrew. Make a virtual environment for your project (Chapter 23) and install packages inside it.

VS Code can’t be found after a restart. You probably ran it from your Downloads folder. Drag Visual Studio Code into Applications, and open it from there.

#Linux

pip or venv is missing. On Ubuntu and Debian, run sudo apt install python3-pip python3-venv. On Fedora, sudo dnf install python3-pip.

error: externally-managed-environment. Your distribution protects its own Python. Use a virtual environment for every project, as Chapter 23 shows.

#VS Code

There’s no Run button. Either the Python extension isn’t installed (Chapter 2), or the file you’re looking at doesn’t end in .py.

A package is installed, but VS Code says ModuleNotFoundError. VS Code is using a different Python from the one you installed into. Open the Command Palette, choose Python: Select Interpreter, and pick the right one (the one inside .venv if you use a virtual environment). Then install the package again from VS Code’s own terminal with python -m pip install.

The program runs, but can’t find its files. Open the project folder (File > Open Folder), not just the file, and build paths with Path(__file__).parent so they work wherever the script is started from.

The program is waiting and nothing happens. It’s probably sitting at an input() line. Click in the terminal panel and type your answer.

The terminal is full of old output. Click the bin icon in the terminal panel to close it, or type cls (Windows) or clear (Mac and Linux).

#Starting again cleanly

If everything is tangled and you’d like a fresh start, that’s a reasonable decision, not a defeat. Uninstall Python (Windows: Settings > Apps; Mac: delete the Python 3.x folder in Applications), restart the computer, and follow Chapter 2 again from the beginning, slowly. Your projects live in your own folders, so you won’t lose any work.