Make as a Task Runner: Phony Targets and Self-Documenting Makefiles

Turn a Makefile into a project's command menu: phony targets, a self-documenting help target, arguments, virtualenvs, bash strict mode and required-variable guards.

By The Dark DebuggerUpdated 32 min read

Most Makefiles written today don't compile anything. They sit at the root of a Python, Go, Node or Terraform repository and give the project a short list of named commands: make test, make lint, make run. This article builds one of those for a small Python tool, and covers the parts that trip people up: .PHONY, a help target that documents itself, passing arguments, virtualenvs, the shell Make uses, and guarding required variables. It assumes Your First Makefile and Variables and How Make Expands Them; the $(if ...) function and ifeq from Conditionals and Portable Makefiles show up once or twice.

Why projects keep a menu of commands

Picture a small Python service. The README says to run the tests with python3 -m unittest discover -s tests -v. The CI configuration has its own copy of that command with slightly different flags. A new contributor types pytest, which isn't installed, and gives up. Six months later nobody remembers how the API docs were built.

A task-runner Makefile fixes this by making the commands themselves the documentation:

  • One entry point for humans and CI. CI runs make ci; so do you, before pushing. When the test command changes, it changes in one place.
  • Discoverable. make help (or plain make) lists what the project can do. Bash completion knows target names, so make <TAB> works too.
  • Language-neutral. Make doesn't care what a recipe runs. The same habits work in every kind of repository, and a polyglot repo gets a single menu.
  • Already installed. GNU Make is on every Linux machine and CI image, so the menu costs contributors nothing.

The target names are a convention more than a standard, but you'll see the same ones everywhere. Here's what they typically run in different ecosystems:

TargetPythonGoNodeTerraform
setup / venvpython3 -m venv .venv, pip install -r ...go mod downloadnpm citerraform init
testpytest or python -m unittestgo test ./...npm testterraform test
lintruff check .go vet ./...npm run lintterraform validate
fmtruff format .gofmt -w .npx prettier --write .terraform fmt -recursive
buildpython -m buildgo build ./cmd/...npm run buildterraform plan -out=tfplan
cleanrm -rf .venv distrm -rf binrm -rf node_modules distrm -rf .terraform

The project

The example is logsum, a little tool that summarizes web server access logs. It uses only the Python standard library, so you can follow along with nothing but python3:

.
├── Makefile
├── logsum
│   ├── __init__.py
│   ├── __main__.py
│   └── parse.py
├── sample
│   └── access.log
└── tests
    ├── __init__.py
    └── test_parse.py

sample/access.log holds a dozen lines in the usual combined log format, plus one junk line left behind by log rotation:

203.0.113.7 - - [09/Nov/2026:10:14:02 +0000] "GET /api/orders HTTP/1.1" 200 512 "-" "curl/8.5.0"
198.51.100.23 - - [09/Nov/2026:10:14:09 +0000] "POST /api/login HTTP/1.1" 401 64 "-" "Mozilla/5.0"
192.0.2.44 - - [09/Nov/2026:10:15:30 +0000] "GET /healthz HTTP/1.1" 200 2 "-" "kube-probe/1.31"
[…]
-- log rotated --
198.51.100.23 - - [09/Nov/2026:10:18:20 +0000] "GET /api/orders/1183 HTTP/1.1" 200 1301 "-" "Mozilla/5.0"

Here is the finished Makefile. The rest of the article takes it apart one feature at a time, including the broken versions that taught me why each line is there.

# logsum: summarize web server access logs.
# Run `make` or `make help` to list the commands.
 
SHELL       := bash
.SHELLFLAGS := -eu -o pipefail -c
 
PYTHON ?= python3
VENV   ?= .venv
PY     := $(VENV)/bin/python
LOG    ?= sample/access.log
ARGS   ?=
TESTS  ?= discover -s tests
 
# $(call require,NAME) stops make with a message if NAME is empty.
require = $(if $(strip $($(1))),,$(error $(1) is not set (try: make $@ $(1)=...)))
 
.DEFAULT_GOAL := help
.PHONY: help venv test lint ci run docs package clean
 
help: ## Show this help
	@grep -hE '^[a-zA-Z0-9_-]+:.*## ' $(MAKEFILE_LIST) | \
		awk 'BEGIN {FS = ":.*## "} {printf "  %-9s %s\n", $$1, $$2}'
 
venv: $(PY) ## Create the virtual environment in .venv
 
$(PY):
	$(PYTHON) -m venv --without-pip $(VENV)
 
test: venv ## Run the tests (choose some with TESTS=...)
	$(PY) -m unittest $(TESTS) -v 2>&1 | tee test-report.txt
 
lint: venv ## Byte-compile everything to catch syntax errors
	$(PY) -m compileall -q logsum tests
 
ci: lint test ## What CI runs: lint, then test
 
run: venv ## Summarize LOG (default: sample/access.log); flags go in ARGS
	$(PY) -m logsum $(LOG) $(ARGS)
 
docs: docs/logsum.parse.html ## Write HTML API docs into docs/
 
docs/logsum.parse.html: logsum/parse.py | $(PY)
	mkdir -p docs
	$(PY) -m pydoc -w logsum.parse
	mv logsum.parse.html $@
 
package: ## Build dist/logsum-VERSION.tar.gz (needs VERSION=x.y.z)
	$(call require,VERSION)
	mkdir -p dist
	tar --exclude=__pycache__ -czf dist/logsum-$(VERSION).tar.gz logsum
	@echo "built dist/logsum-$(VERSION).tar.gz"
 
clean: ## Delete the venv, docs, dist and caches
	rm -rf $(VENV) docs dist test-report.txt
	find . -name __pycache__ -type d -prune -exec rm -rf {} +

Run make with no arguments and the Makefile describes itself:

make
  help      Show this help
  venv      Create the virtual environment in .venv
  test      Run the tests (choose some with TESTS=...)
  lint      Byte-compile everything to catch syntax errors
  ci        What CI runs: lint, then test
  run       Summarize LOG (default: sample/access.log); flags go in ARGS
  docs      Write HTML API docs into docs/
  package   Build dist/logsum-VERSION.tar.gz (needs VERSION=x.y.z)
  clean     Delete the venv, docs, dist and caches

.PHONY in depth

Make's whole model is "a target is a file". A task like test or docs isn't a file, and Make only finds that out when a file or directory with the same name turns up. Here's an early version of the Makefile, before .PHONY listed docs:

.PHONY: test
 
test:
	python3 -m unittest discover -s tests -v
 
docs:
	mkdir -p docs
	python3 -m pydoc -w logsum.parse
	mv logsum.parse.html docs/

The first run works. The second run doesn't, and neither does any run after editing the code:

make docs
make docs
echo '# tweak' >> logsum/parse.py
make docs
mkdir -p docs
python3 -m pydoc -w logsum.parse
wrote logsum.parse.html
mv logsum.parse.html docs/
make: 'docs' is up to date.
make: 'docs' is up to date.

The recipe created a directory called docs. From then on Make saw a target that exists and has no prerequisites, so by its rules there was never anything to do. The docs silently went stale. test is safe from this even if someone creates a test file, because it's listed in .PHONY.

Declaring a target phony tells Make three things:

  1. Always run the recipe when the target is requested, whatever is on disk.
  2. Ignore any file with that name. A docs/ directory or a stray clean file can't shadow the target.
  3. Skip the implicit rule search. Make doesn't waste time looking for a built-in rule that could produce a file called test.

Put every task name in .PHONY. One .PHONY: line near the top listing all of them is the easiest to keep in sync with the targets; several .PHONY: lines are also fine, since they add up.

Don't make a real file depend on a phony target

The opposite mistake is quieter. Here the docs are a real file again, but they depend on the phony venv target:

PY := .venv/bin/python
 
.PHONY: venv docs
 
venv: $(PY)
 
$(PY):
	python3 -m venv --without-pip .venv
 
docs: docs/logsum.parse.html
 
docs/logsum.parse.html: logsum/parse.py venv
	mkdir -p docs
	$(PY) -m pydoc -w logsum.parse
	mv logsum.parse.html $@
make docs
make docs
python3 -m venv --without-pip .venv
mkdir -p docs
.venv/bin/python -m pydoc -w logsum.parse
wrote logsum.parse.html
mv logsum.parse.html docs/logsum.parse.html
mkdir -p docs
.venv/bin/python -m pydoc -w logsum.parse
wrote logsum.parse.html
mv logsum.parse.html docs/logsum.parse.html

The HTML was rebuilt on the second run although nothing changed. A phony target is always considered just remade, so anything that depends on it is always out of date. For two seconds of pydoc that's harmless; for a ten-minute Docker build or a data export it isn't.

The fix, used in the final Makefile, is to depend on the real file the phony target stands for, $(PY), and to make it order-only by putting it after a |:

docs/logsum.parse.html: logsum/parse.py | $(PY)

Order-only means "this must exist before the recipe runs, but its timestamp doesn't matter". Recreating the venv won't trigger a docs rebuild; editing parse.py will:

make docs
make docs
touch logsum/parse.py
make docs
python3 -m venv --without-pip .venv
mkdir -p docs
.venv/bin/python -m pydoc -w logsum.parse
wrote logsum.parse.html
mv logsum.parse.html docs/logsum.parse.html
make: Nothing to be done for 'docs'.
mkdir -p docs
.venv/bin/python -m pydoc -w logsum.parse
wrote logsum.parse.html
mv logsum.parse.html docs/logsum.parse.html

This is the pattern to aim for: a friendly phony name (docs) on the menu, pointing at real files underneath that Make can track. A task runner gets more useful the more of its targets are real files. Order-only prerequisites get a fuller treatment in Parallel Builds, Dependency Generation, and Debugging.

A self-documenting help target

The help target turns comments into the menu. Any target line with a ## description comment is listed; targets without one (like $(PY) and the docs file) stay hidden. The recipe is two commands in a pipeline:

help: ## Show this help
	@grep -hE '^[a-zA-Z0-9_-]+:.*## ' $(MAKEFILE_LIST) | \
		awk 'BEGIN {FS = ":.*## "} {printf "  %-9s %s\n", $$1, $$2}'

Piece by piece:

  • $(MAKEFILE_LIST) is a variable Make maintains itself: every makefile it has read so far, in order. By the time the recipe runs, that includes any included files.
  • grep -hE '^[a-zA-Z0-9_-]+:.*## ' keeps lines that start with a target name and a colon and contain ## later on. Variable assignments like PY := ... don't match because of the space before the colon. -h stops grep printing file names; see below for why that matters.
  • awk's field separator :.*## swallows everything from the first colon to the ## marker, so $1 is the target name and $2 is the description, colons and all.
  • $$1 and $$2 are doubled because Make expands $ before the shell sees the line. A single $1 would be replaced by Make's (empty) variable 1.
  • The leading @ stops Make echoing the command itself. Without it, make help would start with a two-line grep pipeline nobody wants to read.

Targets appear in file order, which lets you group them sensibly. Pipe through sort before awk if you prefer them alphabetical.

Included files need grep -h

Bigger projects split the Makefile up. Say the Docker targets live in mk/docker.mk:

IMAGE ?= registry.example.com/logsum
TAG   ?= dev
 
.PHONY: docker-build docker-push
 
docker-build: ## Build the container image
	docker build -t $(IMAGE):$(TAG) .
 
docker-push: docker-build ## Push the image to the registry
	docker push $(IMAGE):$(TAG)

and the main Makefile includes it at the top, with a help recipe that forgot -h:

include mk/docker.mk
 
.PHONY: help test
 
help: ## Show this help
	@grep -E '^[a-zA-Z0-9_-]+:.*## ' $(MAKEFILE_LIST) | \
		awk 'BEGIN {FS = ":.*## "} {printf "  %-13s %s\n", $$1, $$2}'
 
test: ## Run the tests
	python3 -m unittest discover -s tests
make help
  Makefile      Show this help
  Makefile      Run the tests
  mk/docker.mk  Build the container image
  mk/docker.mk  Push the image to the registry

With more than one file to search, grep prefixes every match with its file name (Makefile:help: ## Show this help), and the awk split then takes the file name as the target. The help worked fine for months with a single Makefile and broke the day someone added an include. Always pass -h.

Choosing the default goal

That same Makefile has a second, nastier problem. Run make with no arguments:

make
docker build -t registry.example.com/logsum:dev .
make: docker: No such file or directory
make: *** [mk/docker.mk:7: docker-build] Error 127

Make's default goal is the first target it reads, and the include on line 1 meant the first target was docker-build. On a machine with Docker, a curious newcomer typing make would have kicked off an image build. (This lab machine has no Docker, hence the error.)

.DEFAULT_GOAL names the default explicitly, wherever the targets happen to be defined. Here's the fixed version, with -h added too:

include mk/docker.mk
 
.DEFAULT_GOAL := help
.PHONY: help test
 
help: ## Show this help
	@grep -hE '^[a-zA-Z0-9_-]+:.*## ' $(MAKEFILE_LIST) | \
		awk 'BEGIN {FS = ":.*## "} {printf "  %-13s %s\n", $$1, $$2}'
 
test: ## Run the tests
	python3 -m unittest discover -s tests
make
  help          Show this help
  test          Run the tests
  docker-build  Build the container image
  docker-push   Push the image to the registry

Should the default be help, or the build? My rule: if the Makefile mainly builds files (a C program, a report), the default should build them, conventionally via a target called all. If it's a menu of tasks, default to help. Running tests, or anything slower or more dangerous, should never be the thing that happens when someone types make to see what's there.

Passing arguments

Make targets don't take arguments the way a script does. What they take is variables. Give every knob a default with ?= and let callers override it with NAME=value after the target:

make run ARGS="--top 5"
.venv/bin/python -m logsum sample/access.log --top 5
200  8
401  1
404  1
500  1
top paths:
    3  /api/orders
    3  /healthz
    2  /api/login
    1  /api/orders/1182
    1  /wp-login.php
unparsed lines: 1

TESTS works the same way, which is handy when you're iterating on one failing test:

make test TESTS=tests.test_parse.SummaryTest
.venv/bin/python -m unittest tests.test_parse.SummaryTest -v 2>&1 | tee test-report.txt
test_counts (tests.test_parse.SummaryTest.test_counts) ... ok
 
----------------------------------------------------------------------
Ran 1 test in 0.001s
 
OK

Command line, environment, or Makefile?

Variables can also come from the environment, and ?= versus := decides whether that works. This small Makefile shows the difference:

LOG ?= sample/access.log
REGION := eu-west-1
 
.PHONY: show
show:
	@echo "LOG=$(LOG) REGION=$(REGION)"
make show
LOG=/var/log/nginx/access.log make show
REGION=us-east-1 make show
make show REGION=us-east-1
LOG=sample/access.log REGION=eu-west-1
LOG=/var/log/nginx/access.log REGION=eu-west-1
LOG=sample/access.log REGION=eu-west-1
LOG=sample/access.log REGION=us-east-1

An environment variable only wins against ?=, which means "set this unless it's already set". A plain := or = assignment in the Makefile beats the environment. Command-line assignments beat both. So: use ?= for anything a developer or CI job may want to set from the environment, and tell people to pass values after the target (make show REGION=...), which always works. The full precedence rules, and override, are in Variables and How Make Expands Them.

Things that look like arguments but aren't

Everything after make is either an option, a NAME=value assignment, or a target. Flags meant for your program end up as one of the wrong two:

make run --top 5
make: unrecognized option '--top'
Usage: make [options] [target] ...
Options:
  -b, -m                      Ignored for compatibility.
[…]
make run 5
.venv/bin/python -m logsum sample/access.log 
200  8
[…]
unparsed lines: 1
make: *** No rule to make target '5'.  Stop.

--top went to Make, which rejected it. 5 was taken as a second goal: Make ran run, then failed on a target called 5. Even with the variable, quoting matters, because the shell splits ARGS=--top 5 into two words before Make sees them:

make run ARGS=--top 5
.venv/bin/python -m logsum sample/access.log --top
usage: logsum [-h] [--top TOP] logfile
logsum: error: argument --top: expected one argument
make: *** [Makefile:38: run] Error 2

You'll find tricks online that read extra goals out of $(MAKECMDGOALS) and add a catch-all %: rule so that make run 5 "works". I don't recommend them: they make typos in target names silently succeed. If a command really needs positional arguments, that's a sign it wants to be a script in scripts/ that the Makefile calls.

Running commands inside a virtualenv

Here's the recipe almost everyone writes first, straight from the instructions they'd type in a terminal:

.PHONY: test
 
test:
	source .venv/bin/activate
	python -m unittest discover -s tests -v
make test
source .venv/bin/activate
make: source: No such file or directory
make: *** [Makefile:4: test] Error 127

Make runs recipes with /bin/sh, which on Ubuntu is dash, and dash has no source. (The message says make: rather than /bin/sh: because for a simple command with no shell syntax in it, GNU Make skips the shell and executes the program directly, and there is no program called source.) The POSIX spelling is ., so try that:

.PHONY: test
 
test:
	. .venv/bin/activate
	python -m unittest discover -s tests -v
. .venv/bin/activate
python -m unittest discover -s tests -v
make: python: No such file or directory
make: *** [Makefile:5: test] Error 127

The activation worked, in a shell that exited immediately afterwards. Each recipe line runs in its own shell, so the second line started fresh, without the venv's bin directory on its PATH. Ubuntu doesn't ship a bare python command, hence the error. On a machine where python does exist, this recipe is worse: it silently runs the tests with the system Python.

The fix is not to activate anything. Activation only edits PATH; calling the venv's interpreter by its path does the same job, on every line, in any shell. In the final Makefile, PY := $(VENV)/bin/python, and:

$(PY):
	$(PYTHON) -m venv --without-pip $(VENV)
 
test: venv ## Run the tests (choose some with TESTS=...)
	$(PY) -m unittest $(TESTS) -v 2>&1 | tee test-report.txt

The venv is a real file target, .venv/bin/python, so Make creates it once and then leaves it alone. The first make test on a fresh checkout builds it on the way:

make test
python3 -m venv --without-pip .venv
.venv/bin/python -m unittest discover -s tests -v 2>&1 | tee test-report.txt
test_bad_line (test_parse.ParseTest.test_bad_line) ... ok
test_good_line (test_parse.ParseTest.test_good_line) ... ok
test_counts (test_parse.SummaryTest.test_counts) ... ok
 
----------------------------------------------------------------------
Ran 3 tests in 0.001s
 
OK

--without-pip is there because logsum has no third-party dependencies, and because the Ubuntu machine I tested on doesn't have the python3.12-venv package that provides pip for new venvs (see Common mistakes for that error).

Projects with dependencies

Most real projects install packages into the venv. The usual shape is a stamp file that depends on the requirements file, so editing requirements-dev.txt re-runs the install:

$(VENV)/.installed: requirements-dev.txt
	$(PYTHON) -m venv $(VENV)
	$(VENV)/bin/pip install -r requirements-dev.txt
	touch $@

The test machine had no pip, so this fragment was not run; the stamp-file mechanics are the same ones you'll build and test in Exercise 3. Tools installed this way are called by path too: $(VENV)/bin/pytest, $(VENV)/bin/ruff.

SHELL, .SHELLFLAGS and bash strict mode

The test recipe pipes the test output through tee so CI can keep a copy. With Make's default shell, that pipeline hides failures. Here's the recipe on its own, using /bin/sh:

PY := .venv/bin/python
 
.PHONY: test
test:
	$(PY) -m unittest discover -s tests 2>&1 | tee test-report.txt

I broke the parser on purpose (it stopped converting the status code to an integer) and ran the tests:

make test; echo "make exit status: $?"
.venv/bin/python -m unittest discover -s tests 2>&1 | tee test-report.txt
.FF
======================================================================
FAIL: test_good_line (test_parse.ParseTest.test_good_line)
----------------------------------------------------------------------
[…]
AssertionError: '200' != 200
[…]
Ran 3 tests in 0.002s
 
FAILED (failures=2)
make exit status: 0

Two tests failed and Make reported success. A pipeline's exit status is the status of its last command, and tee succeeded. In CI this is a green build with broken code.

SHELL chooses the shell Make runs recipes with, and .SHELLFLAGS the flags it passes (default -c). The final Makefile sets both, which is often called bash strict mode:

SHELL       := bash
.SHELLFLAGS := -eu -o pipefail -c

Same broken code, real Makefile:

make test; echo "make exit status: $?"
.venv/bin/python -m unittest discover -s tests -v 2>&1 | tee test-report.txt
test_bad_line (test_parse.ParseTest.test_bad_line) ... ok
test_good_line (test_parse.ParseTest.test_good_line) ... FAIL
test_counts (test_parse.SummaryTest.test_counts) ... FAIL
[…]
FAILED (failures=2)
make: *** [Makefile:30: test] Error 1
make exit status: 2

What each flag does inside a recipe line:

FlagEffectBug it catches
-o pipefailA pipeline fails if any command in it failstests | tee log reporting success
-eStop at the first failing command in a line like a; b or a multi-line .ONESHELL recipecd build; rm -rf * continuing after a failed cd
-uReferencing an unset shell variable is an errorrm -rf "$$DEST/" with DEST unset
-cRead the command from the next argumentRequired, and must come last

Two details: SHELL is never taken from your environment (your login shell doesn't change how Makefiles run), and bash must exist wherever the Makefile runs. On Linux and in CI images that's a given; on Alpine-based containers it often isn't.

.ONESHELL: one shell per recipe

Sometimes a recipe really is a little script, with a variable and an if. Line by line, that doesn't work:

LOG ?= sample/access.log
 
.PHONY: check-errors
check-errors:
	errors=$$(grep -c '" 5[0-9][0-9] ' $(LOG))
	if [ "$$errors" -gt 0 ]; then
		echo "$(LOG): $$errors responses with status 5xx"
		exit 1
	fi
make check-errors
errors=$(grep -c '" 5[0-9][0-9] ' sample/access.log)
if [ "$errors" -gt 0 ]; then
/bin/sh: 1: Syntax error: end of file unexpected (expecting "fi")
make: *** [Makefile:6: check-errors] Error 2

The second line went to a new shell on its own, an if with no fi. Even if it had parsed, errors would have been empty there. The traditional fix is to join the lines with ; \ into one long logical line. The GNU Make 3.82+ alternative is the special target .ONESHELL, which sends the whole recipe to a single shell. Adding .ONESHELL: at the top of the same file:

errors=$(grep -c '" 5[0-9][0-9] ' sample/access.log)
if [ "$errors" -gt 0 ]; then
echo "sample/access.log: $errors responses with status 5xx"
exit 1
fi
sample/access.log: 1 responses with status 5xx
make: *** [Makefile:7: check-errors] Error 1

Make echoed the whole script, ran it once, and the exit 1 failed the target as intended.

The catch: failures in the middle are ignored

Normally a failing recipe line stops Make. With .ONESHELL, Make only sees the exit status of the whole script, which is the status of its last command:

.ONESHELL:
 
.PHONY: backup
backup:
	mkdir -p /var/backups/logsum
	cp sample/access.log /var/backups/logsum/
	echo "backup complete"
make backup
mkdir -p /var/backups/logsum
cp sample/access.log /var/backups/logsum/
echo "backup complete"
mkdir: cannot create directory ‘/var/backups/logsum’: Permission denied
cp: cannot create regular file '/var/backups/logsum/': Not a directory
backup complete

Both commands failed, the script printed "backup complete", and Make exited 0. Add -e to the shell flags and it stops where it should:

.ONESHELL:
.SHELLFLAGS := -ec
 
.PHONY: backup
backup:
	@mkdir -p /var/backups/logsum
	cp sample/access.log /var/backups/logsum/
	echo "backup complete"
mkdir: cannot create directory ‘/var/backups/logsum’: Permission denied
make: *** [Makefile:6: backup] Error 1

Notice that the script wasn't echoed this time. Under .ONESHELL, the @, - and + prefixes on the first line apply to the whole recipe.

.ONESHELL applies to every recipe in the makefile; you can't turn it on for one target. My advice: if you use it, always pair it with -e (the bash strict-mode flags above include it), and once a recipe grows past a handful of lines, move it into a script under scripts/ where it can be linted with shellcheck and run on its own.

Guarding required variables

make package needs a version number, and there's no sensible default. The require function stops Make with a clear message when a variable is missing:

require = $(if $(strip $($(1))),,$(error $(1) is not set (try: make $@ $(1)=...)))

$($(1)) is the value of the variable whose name is the first argument, $(if ...) picks its third argument (the error) when that value is empty, and $@ is the current target. Use it as the first line of the recipe:

make package
make package VERSION=1.4.0
tar -tzf dist/logsum-1.4.0.tar.gz
Makefile:48: *** VERSION is not set (try: make package VERSION=...).  Stop.
mkdir -p dist
tar --exclude=__pycache__ -czf dist/logsum-1.4.0.tar.gz logsum
built dist/logsum-1.4.0.tar.gz
logsum/
logsum/__main__.py
logsum/parse.py
logsum/__init__.py

Why does the error stop mkdir and tar from running, when it's only on the first line? Make expands every line of a recipe before it runs the first one, so the $(error ...) fires before any command starts. (The --exclude is there because my first version of this target shipped __pycache__ directories in the tarball. Listing an archive after building it is a habit worth having.)

Where you put a guard matters:

  • Inside the recipe (as here), it fires only when that target actually runs. make help and make test work without VERSION.
  • At the top level (ifndef VERSION / $(error ...) outside any rule), it fires on every invocation, including make help. That's only right for something every target needs. Conditionals and Portable Makefiles shows how MAKECMDGOALS can limit a top-level check to particular goals.

Where you'll use this

The payoff is that "what does CI do?" and "what should I run before pushing?" have the same one-word answer. A CI job for this project is checkout, install Python, and make ci. When a test command changes, the workflow file doesn't.

A release check chains goals in one invocation. Make processes them left to right:

make clean ci package VERSION=1.4.0
rm -rf .venv docs dist test-report.txt
find . -name __pycache__ -type d -prune -exec rm -rf {} +
python3 -m venv --without-pip .venv
.venv/bin/python -m compileall -q logsum tests
.venv/bin/python -m unittest discover -s tests -v 2>&1 | tee test-report.txt
test_bad_line (test_parse.ParseTest.test_bad_line) ... ok
test_good_line (test_parse.ParseTest.test_good_line) ... ok
test_counts (test_parse.SummaryTest.test_counts) ... ok
 
----------------------------------------------------------------------
Ran 3 tests in 0.001s
 
OK
mkdir -p dist
tar --exclude=__pycache__ -czf dist/logsum-1.4.0.tar.gz logsum
built dist/logsum-1.4.0.tar.gz

From a clean checkout to a tested tarball, with every step visible. Don't add -j to a line like this: with parallel jobs clean could run while package is writing. Other places the same pattern pays off:

  • Go services, where make build wraps go build with -ldflags that stamp the version and commit, a line nobody wants to type.
  • Docker workflows: make docker-build docker-push TAG=1.4.0 hides the registry name and build arguments, as in the mk/docker.mk fragment above.
  • Terraform repositories: make plan ENV=staging expands to the right -chdir, var-file and workspace. Real-World Makefiles builds a wrapper like that and runs it.
  • Monorepos, where the root Makefile calls into each component. That's the subject of Multi-Directory Projects.

When to use just, Task or npm scripts instead

Make is a build tool that happens to make a decent task runner. Purpose-built runners exist, and sometimes they're the better choice:

ToolChoose it whenThe trade-off
npm scriptsIt's a JavaScript project and everyone already has NodeShell portability is on you; awkward beyond one-liners
justYou want real recipe arguments (just deploy staging), no TAB rule, clearer errorsDoesn't track files, so it can't skip up-to-date work; must be installed everywhere
Task (Taskfile.yml)You need Windows without a Unix shell, or want checksum-based "skip if unchanged"YAML, and another binary to install
MakeAny Unix-like dev box and CI image, outputs that are real files, polyglot reposThe TAB rule, $$ escaping, line-per-shell recipes, no native arguments

My take: if your team works on Linux or macOS and the menu is a dozen targets, Make is the lowest-friction choice, because it's already installed and it can also build things. If you're writing recipes that are mostly shell logic with arguments, or your contributors are on plain Windows, a dedicated runner will annoy people less. I didn't install just or Task for this article; the table reflects their documentation.

Common mistakes

A venv that failed halfway looks finished

On a stock Ubuntu install, python3 -m venv fails because pip's bootstrap module is packaged separately. With this rule:

PY := .venv/bin/python
 
.PHONY: venv test
 
venv: $(PY)
 
$(PY):
	python3 -m venv .venv
 
test: venv
	$(PY) -m unittest discover -s tests

the first run fails loudly:

make test
python3 -m venv .venv
The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.
 
    apt install python3.12-venv
 
You may need to use sudo with that command.  After installing the python3-venv
package, recreate your virtual environment.
 
[…]
make: *** [Makefile:8: .venv/bin/python] Error 1

Run it again, though, and it "works". venv had already created .venv/bin/python before it failed, so Make considered the target built:

.venv/bin/python -m unittest discover -s tests
...
----------------------------------------------------------------------
Ran 3 tests in 0.001s
 
OK

Here the tests pass, but a real project would now fail on a missing pip, far from the cause. There are two fixes. The direct one is installing python3.12-venv (or using --without-pip if you need no packages). The general one is adding the special target .DELETE_ON_ERROR: to the Makefile, which tells Make to delete a target whose recipe failed. With it, the failed run ends with:

make: *** [Makefile:10: .venv/bin/python] Error 1
make: *** Deleting file '.venv/bin/python'

and every later run retries instead of trusting a half-built venv. I recommend .DELETE_ON_ERROR: in every Makefile; it's covered properly in Parallel Builds, Dependency Generation, and Debugging.

Tests fail but make exits 0

If a recipe pipes into tee, grep or anything else, its failures are invisible under the default /bin/sh, as shown in the strict-mode section. Check yours with make test; echo $? after breaking a test on purpose. The fix is SHELL := bash with .SHELLFLAGS := -eu -o pipefail -c.

make: unrecognized option or No rule to make target '5'

Flags and positional values after make belong to Make, not to your recipe. Pass them in a variable, and quote the value when it contains spaces: make run ARGS="--top 5".

The help shows file names instead of targets

make help prints Makefile and mk/docker.mk in the name column: grep is searching more than one file and prefixing its matches. Add -h to the grep.

Summary

  • A task-runner Makefile gives a project one discoverable set of commands shared by people and CI. Put every task name in .PHONY, or a file or directory with that name will silently make the task "up to date".
  • Never make a real file depend on a phony target; it will rebuild every time. Depend on the real file behind it, order-only (| $(PY)) if only its existence matters.
  • help built from ## comments with grep -h ... $(MAKEFILE_LIST) | awk keeps the menu in sync with the code. Set .DEFAULT_GOAL := help so include order can't change what make does.
  • Targets take variables, not arguments: ?= defaults, make run ARGS="--top 5". Command line beats Makefile beats environment, except that ?= lets the environment in.
  • Every recipe line is a new /bin/sh. Activating a venv doesn't survive to the next line; call $(VENV)/bin/python directly and make the venv a real file target.
  • SHELL := bash with .SHELLFLAGS := -eu -o pipefail -c stops pipelines into tee hiding failures. .ONESHELL runs a recipe as one script but needs -e to stop on errors.
  • $(call require,VERSION) on the first recipe line fails fast, because Make expands the whole recipe before running any of it.

Exercises

All four start from the finished Makefile in The project.

Exercise 1: Add a target to the menueasy

Add a stats target that prints how many lines LOG has, for example 12 lines in sample/access.log. It should appear in make help between run and docs, and make stats should print only the result, not the command.

Hint

The help order is file order. Inside a recipe, shell command substitution needs $$( ... ).

Show Solution

Add stats to .PHONY and put this rule after run:

stats: ## Count the lines in LOG
	@echo "$$(wc -l < $(LOG)) lines in $(LOG)"
make help
make stats
  help      Show this help
  venv      Create the virtual environment in .venv
  test      Run the tests (choose some with TESTS=...)
  lint      Byte-compile everything to catch syntax errors
  ci        What CI runs: lint, then test
  run       Summarize LOG (default: sample/access.log); show TOP paths
  stats     Count the lines in LOG
  docs      Write HTML API docs into docs/
  package   Build dist/logsum-VERSION.tar.gz (needs VERSION=x.y.z)
  deploy    Deploy VERSION to ENV (staging or production)
  clean     Delete the venv, docs, dist and caches
12 lines in sample/access.log

(This help output is from my copy with all four exercises done, which is why run reads slightly differently and deploy is there.) The @ hides the command, and $$(...) reaches the shell as $(...). With a single $, Make would try to expand a variable named wc -l < sample/access.log and substitute an empty string.

Exercise 2: Replace ARGS with a named variableeasy

make run ARGS="--top 5" makes people remember the program's flag. Change the run target so make run TOP=1 shows only the single most requested path, with a default of 3. Update the help text.

Show Solution
TOP    ?= 3
run: venv ## Summarize LOG (default: sample/access.log); show TOP paths
	$(PY) -m logsum $(LOG) --top $(TOP)
make run TOP=1
.venv/bin/python -m logsum sample/access.log --top 1
200  8
401  1
404  1
500  1
top paths:
    3  /api/orders
unparsed lines: 1

A named variable with a ?= default is self-documenting and can't be mis-quoted the way a free-form ARGS can. Keep ARGS as well if you also want an escape hatch for rarely used flags.

Exercise 3: Recreate the venv when requirements changemedium

Create an empty requirements.txt. Change the Makefile so the venv is recreated from scratch whenever requirements.txt is newer than it, but left alone otherwise. Check it with make venv twice, then touch requirements.txt and make venv again.

Hint

.venv/bin/python is a poor target for this: it's a symlink, and Make checks the timestamp of the file a symlink points to. Make a stamp file that the recipe touches last, and point everything that needs the venv at the stamp.

Show Solution
venv: $(VENV)/.stamp ## Create the virtual environment in .venv
 
$(VENV)/.stamp: requirements.txt
	rm -rf $(VENV)
	$(PYTHON) -m venv --without-pip $(VENV)
	touch $@

The docs rule changes to docs/logsum.parse.html: logsum/parse.py | $(VENV)/.stamp. With the venv already built:

make venv
touch requirements.txt
make venv
make: Nothing to be done for 'venv'.
rm -rf .venv
python3 -m venv --without-pip .venv
touch .venv/.stamp

I tried the obvious version first, $(PY): requirements.txt, and it rebuilt the venv on every single run. stat shows why:

stat -c "%y %n" requirements.txt .venv/bin/python; stat -L -c "%y %n" .venv/bin/python
2026-11-09 21:56:55.532901643 -0500 requirements.txt
2026-11-09 21:56:55.634561054 -0500 .venv/bin/python
2026-08-31 06:18:26.000000000 -0400 .venv/bin/python

The symlink itself is new, but Make follows it to /usr/bin/python3, installed months ago and always older than requirements.txt. (make -L compares symlink times instead, but you don't want every caller to need a flag.) A stamp file is an ordinary file, so its time is the time the recipe finished.

The stamp is written by the last line of the recipe, so it only exists if everything before it succeeded. That also fixes the half-built venv problem from Common mistakes without needing .DELETE_ON_ERROR. In a project with dependencies, the pip install line goes just before the touch.

Exercise 4: Guard a deploy targethard

Add a deploy target that requires both VERSION and ENV, refuses any ENV other than staging or production, and then prints deploying logsum VERSION to ENV. Each failure should name the problem. Test all four cases: nothing set, only VERSION, ENV=prod, and a valid call.

Hint

$(filter $(ENV),staging production) is empty when ENV isn't one of the two words.

Show Solution
deploy: ## Deploy VERSION to ENV (staging or production)
	$(call require,VERSION)
	$(call require,ENV)
	$(if $(filter $(ENV),staging production),,$(error ENV must be staging or production, not '$(ENV)'))
	@echo "deploying logsum $(VERSION) to $(ENV)"
make deploy
make deploy VERSION=1.4.0
make deploy VERSION=1.4.0 ENV=prod
make deploy VERSION=1.4.0 ENV=staging
Makefile:59: *** VERSION is not set (try: make deploy VERSION=...).  Stop.
Makefile:60: *** ENV is not set (try: make deploy ENV=...).  Stop.
Makefile:61: *** ENV must be staging or production, not 'prod'.  Stop.
deploying logsum 1.4.0 to staging

All three checks are expanded before the echo runs, so a bad ENV can't get as far as a real deploy command. The line numbers point at the guard that fired, which helps when a teammate pastes the error into a chat.


Tested with: GNU Make 4.3, GNU Bash 5.2.21 and Python 3.12.3 on Ubuntu 24.04 (WSL2), November 2026. Every Makefile and command above was run as shown, and the outputs are verbatim; I trimmed tracebacks and the long make usage text where marked […]. The lab had no Docker, so the Docker targets only got as far as the "No such file or directory" error shown, and no pip, so the pip install fragment in the callout is the one thing here that was not executed. GitHub Actions, just and Task were not run.

Was this page helpful?
The Dark Debugger

Written by The Dark Debugger

Engineer documenting the things that took me too long to learn, so they take you less time. Every Makefile tutorial here is tested end to end before publishing.