2. Setting up your environment

Before we write any tests, let's get you a clean project to put them in. This page walks through creating a Python environment with pytest installed. It takes about two minutes, and by the end you'll have everything you need for the rest of the guide.

If you already have a Python project with pytest set up, feel free to skip to the next section.

This guide assumes Python 3.10 or later. Check yours with python --version. If it prints something older, grab a newer one from python.org before continuing.

Create a project folder

Pick a short path on your machine and make a new folder for this project. Something like:

C:\dev\weather-client

On macOS or Linux, ~/dev/weather-client works the same way. Short paths keep your terminal output tight, which matters more than you'd think once you start copying errors and sharing screenshots with teammates.

Open the folder in your editor. The rest of the commands in this guide run from inside it.

Create a virtual environment

Python projects share the global interpreter by default. Every time you run pip install, the package goes into the same bucket, so packages from one project can accidentally affect another, and two projects that need different versions of the same library will fight.

The fix is a virtual environment: a private Python setup scoped to one project, with its own package list. Enter the following command to create one from inside your project folder:

python -m venv .venv

That creates a hidden .venv/ folder containing a private Python interpreter and an empty package list. You only do this once per project.

Activate the environment

Activation tells your terminal “when I type python or pip, use the one inside .venv.” The command is slightly different depending on your OS.

On Windows (PowerShell):

.venv\Scripts\Activate.ps1

On macOS or Linux:

source .venv/bin/activate

You'll know it worked when your prompt picks up a (.venv) prefix:

(.venv) PS C:\dev\weather-client>

Watch for that prefix throughout the rest of the guide. If it's missing, you're running the global Python and things will go wrong in confusing ways. When in doubt, rerun the activate command.

One small gotcha if you're using VS Code: activating the venv in your terminal doesn't automatically tell VS Code's editor about it. For IntelliSense and test discovery to use the right interpreter, hit Ctrl+Shift+P → type Python: Select Interpreter → pick the one inside .venv. The bottom-right status bar will confirm it picked up .venv (3.12.x).

Configure pytest in VS Code

If you use VS Code, create a .vscode/settings.json file so its Testing panel knows to use pytest and search the tests/ folder. This requires Microsoft's Python extension; terminal users can skip this file entirely.

{
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false,
  "python.testing.pytestArgs": ["tests"]
}

Install pytest

With the environment active, install pytest:

python -m pip install pytest

Calling pip through python -m pip ensures the installer belongs to the Python interpreter selected by your active environment. Verify the installation with:

pytest --version

You should see a pytest version number. If you do, you're ready to write tests.

Point pytest at your code

One last piece of setup saves a confusing error later. Your tests will live in a tests/ folder, but the code they import (app.py, weather_client.py, and friends) will sit in the project root. By default pytest doesn't put the project root on Python's import path, so from app import app fails with ModuleNotFoundError the first time you import your own code. A one-line pyproject.toml fixes it permanently:

[tool.pytest.ini_options]
pythonpath = ["."]

That tells pytest to treat the project root as an import root, so your test files can import your modules by name no matter where you run pytest from. Create the file now and you won't think about it again.

Freeze your dependencies

One more habit worth picking up before we move on. Run:

python -m pip freeze > requirements.txt

That writes a requirements.txt file listing every package in your environment with its exact version. It's how Python projects communicate their dependencies. If a teammate (or future-you on a new machine) wants to recreate your environment, one command does it:

python -m pip install -r requirements.txt

Re-run the freeze any time you install a new package. It's a habit that costs nothing and saves you from “but it works on my machine” arguments later.

Ignore the junk

If you plan to put this project under version control (and you should), create a .gitignore file at the project root with these lines:

.venv/
__pycache__/
*.pyc
.pytest_cache/

Those are the generated folders and bytecode that shouldn't be committed. Every Python project has roughly the same list, and once you've seen it a few times you'll write it from memory.

You're ready

Your project folder should now look something like this:

weather-client/
├── .venv/
├── .vscode/
│   └── settings.json
├── .gitignore
├── pyproject.toml
└── requirements.txt

That's the whole setup. Every other command in this guide assumes you're sitting in this folder with the venv active. Next, we'll write our first test and watch it pass.