Setting up a Python project

Engineering Toolkit, lesson 7

A project anyone can install, run and test the same way anywhere.

"Pipes, variables and scripts" for PATH and environment variables, and some Python.

Part 1. One environment per project

Install packages with plain pip install for long enough and two projects will want different versions of the same one. The fix is an environment per project: a folder holding its own Python and its own packages, so nothing one project installs can touch another.

Your turn

Two projects share one environment. Project A needs pandas 1.5 and project B needs pandas 2.2. You install B's requirements. What happens to A?

An environment holds one version of each package, so installing B's pandas removes A's. pip may print a warning about the conflict, but only if A's own package records that it needs pandas 1.5. Separate environments make the problem go away.

Show the answer

D. An environment holds one version of each package, so installing B's pandas removes A's. pip may print a warning about the conflict, but only if A's own package records that it needs pandas 1.5. Separate environments make the problem go away.

Making and activating an environment

$ cd textstats
$ python3 -m venv .venv
$ source .venv/bin/activate
$ which python
/home/ana/textstats/.venv/bin/python
$ which pip
/home/ana/textstats/.venv/bin/pip

Once it's active, your prompt starts with (.venv), and python and pip mean the ones inside .venv. Activating works by putting .venv/bin at the front of PATH. On Windows the command is .venv\Scripts\activate, and deactivate switches it off anywhere. Each new terminal needs activating again.

Installing into it

$ python -m pip install pytest
Collecting pytest
  Downloading pytest-9.2.0-py3-none-any.whl.metadata (7.9 kB)
...
Installing collected packages: pygments, pluggy, packaging, iniconfig, pytest
Successfully installed iniconfig-2.3.1 packaging-26.3 pluggy-1.7.0 pygments-2.21.0 pytest-9.2.0

Virtual environment

A folder, usually .venv, with its own Python and its own installed packages, for one project. Activating it puts it first on PATH. It's rebuilt from a list, never committed.

In practice

python -m pip runs the pip that belongs to whichever python you're using, which avoids installing into the wrong place. Tools such as uv, Poetry and conda make and fill environments for you; the idea underneath is the same.

Part 2. A package layout

Keep going with Pro

You've done the first part. Pro opens the rest of this lesson, and every other one.

Still to come

A package layout
Pinning what you depend on
Tests with pytest

See Pro plans I have Pro: sign in

Next lessonSQL queries: filter, join and groupAsk a database questions with SELECT, WHERE, JOIN and GROUP BY. Start lesson 8

Engineering Toolkit overviewSpotted a mistake? Tell us.

07 · Setting up a Python project