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 plainmake) lists what the project can do. Bash completion knows target names, somake <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:
| Target | Python | Go | Node | Terraform |
|---|---|---|---|---|
setup / venv | python3 -m venv .venv, pip install -r ... | go mod download | npm ci | terraform init |
test | pytest or python -m unittest | go test ./... | npm test | terraform test |
lint | ruff check . | go vet ./... | npm run lint | terraform validate |
fmt | ruff format . | gofmt -w . | npx prettier --write . | terraform fmt -recursive |
build | python -m build | go build ./cmd/... | npm run build | terraform plan -out=tfplan |
clean | rm -rf .venv dist | rm -rf bin | rm -rf node_modules dist | rm -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.pysample/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 docsmkdir -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:
- Always run the recipe when the target is requested, whatever is on disk.
- Ignore any file with that name. A
docs/directory or a straycleanfile can't shadow the target. - 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 docspython3 -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.htmlThe 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 docspython3 -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.htmlThis 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 anyincluded files.grep -hE '^[a-zA-Z0-9_-]+:.*## 'keeps lines that start with a target name and a colon and contain##later on. Variable assignments likePY := ...don't match because of the space before the colon.-hstops grep printing file names; see below for why that matters.- awk's field separator
:.*##swallows everything from the first colon to the##marker, so$1is the target name and$2is the description, colons and all. $$1and$$2are doubled because Make expands$before the shell sees the line. A single$1would be replaced by Make's (empty) variable1.- The leading
@stops Make echoing the command itself. Without it,make helpwould 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 testsmake help Makefile Show this help
Makefile Run the tests
mk/docker.mk Build the container image
mk/docker.mk Push the image to the registryWith 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:
makedocker build -t registry.example.com/logsum:dev .
make: docker: No such file or directory
make: *** [mk/docker.mk:7: docker-build] Error 127Make'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 testsmake help Show this help
test Run the tests
docker-build Build the container image
docker-push Push the image to the registryShould 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: 1TESTS 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
OKCommand 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-1LOG=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-1An 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 5make: 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 2You'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 -vmake testsource .venv/bin/activate
make: source: No such file or directory
make: *** [Makefile:4: test] Error 127Make 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 127The 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.txtThe 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 testpython3 -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.txtI 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: 0Two 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 -cSame 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: 2What each flag does inside a recipe line:
| Flag | Effect | Bug it catches |
|---|---|---|
-o pipefail | A pipeline fails if any command in it fails | tests | tee log reporting success |
-e | Stop at the first failing command in a line like a; b or a multi-line .ONESHELL recipe | cd build; rm -rf * continuing after a failed cd |
-u | Referencing an unset shell variable is an error | rm -rf "$$DEST/" with DEST unset |
-c | Read the command from the next argument | Required, 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
fimake check-errorserrors=$(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 2The 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 1Make 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 backupmkdir -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 completeBoth 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 1Notice 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.gzMakefile: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__.pyWhy 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 helpandmake testwork withoutVERSION. - At the top level (
ifndef VERSION/$(error ...)outside any rule), it fires on every invocation, includingmake help. That's only right for something every target needs. Conditionals and Portable Makefiles shows howMAKECMDGOALScan 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.0rm -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.gzFrom 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 buildwrapsgo buildwith-ldflagsthat stamp the version and commit, a line nobody wants to type. - Docker workflows:
make docker-build docker-push TAG=1.4.0hides the registry name and build arguments, as in themk/docker.mkfragment above. - Terraform repositories:
make plan ENV=stagingexpands 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:
| Tool | Choose it when | The trade-off |
|---|---|---|
| npm scripts | It's a JavaScript project and everyone already has Node | Shell portability is on you; awkward beyond one-liners |
| just | You want real recipe arguments (just deploy staging), no TAB rule, clearer errors | Doesn'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 |
| Make | Any Unix-like dev box and CI image, outputs that are real files, polyglot repos | The 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 teststhe first run fails loudly:
make testpython3 -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 1Run 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
OKHere 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. helpbuilt from##comments withgrep -h ... $(MAKEFILE_LIST) | awkkeeps the menu in sync with the code. Set.DEFAULT_GOAL := helpsoincludeorder can't change whatmakedoes.- 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/pythondirectly and make the venv a real file target. SHELL := bashwith.SHELLFLAGS := -eu -o pipefail -cstops pipelines intoteehiding failures..ONESHELLruns a recipe as one script but needs-eto 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.
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.
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 ?= 3run: 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: 1A 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.
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 venvmake: Nothing to be done for 'venv'.
rm -rf .venv
python3 -m venv --without-pip .venv
touch .venv/.stampI 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/python2026-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/pythonThe 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.
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=stagingMakefile: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 stagingAll 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.
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.