Introduction

If you are tired of typing repetitive commands such as pip install, docker build or hugo server, it is time to get to know the Makefile. This tool, present on Unix systems for decades, is still one of the most efficient ways to automate tasks in a developer’s daily routine — and it fits perfectly with modern CI/CD flows, like the ones I covered in Azure DevOps pipelines.

A Makefile is a rules file interpreted by the GNU Make utility, which organizes named tasks (targets) and their dependencies. With it, you replace sequences of manual commands with simple calls such as make build, make test or make deploy. The result is a standardized, reproducible and documented workflow — essential qualities for teams that value consistency.

In this article, I explore the structure of a Makefile, build practical examples for Python, Hugo and Docker, and then combine everything into a single multi-project Makefile. By the end, you will have ready-to-use templates to apply to your projects right away.

This content is aimed at developers, DevOps engineers and technical content creators who want to gain productivity by eliminating repetitive tasks. If you have never used make or want to improve how you use it, keep reading.


What a Makefile Is and Why to Use One

A Makefile is a text file that describes build rules and task automation. Originally created to compile C programs, it evolved and today is used to automate any kind of command-line operation.

Main benefits

  • Automation: avoids repeating commands manually. A single make test replaces a whole sequence of steps.
  • Standardization: everyone on the team uses the same commands, reducing “it works on my machine”.
  • Productivity: a single command for complex multi-step tasks.
  • CI/CD integration: pipelines can call make build, make test, make deploy — making the Makefile a unified interface between local development and automation.
  • Self-documentation: target names serve as documentation of the available flows.

ℹ️ Info: make comes preinstalled on most Linux distributions and on macOS. On Windows, you can use make through WSL, Chocolatey (choco install make) or Git Bash.


Basic Structure of a Makefile

Before looking at real examples, it is essential to understand the anatomy of a Makefile. The structure is simple, but it has strict formatting rules.

1
2
3
4
# Basic structure of a target
target: dependencies
    comando1
    comando2
ElementDescription
targetTask name (e.g., build, test, deploy)
dependenciesOther targets that must run first (optional)
commandsEach line starts with a TAB (not spaces!) — this is rule #1

Essential concepts

  • .PHONY: declares targets that do not correspond to real files. Without it, if a file named build exists in the directory, make build may get confused and run nothing.
  • Variables: let you reuse values such as paths, image names and versions.
  • Dependencies: ensure steps run in the correct order (e.g., deploy depends on build).
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Example with .PHONY and variables
.PHONY: build test

PYTHON := python3
VENV := .venv

build: $(VENV)
    $(PYTHON) -m pip install -r requirements.txt

$(VENV):
    $(PYTHON) -m venv $(VENV)

⚠️ Warning: Command indentation must be a TAB, not spaces. This is the most common beginner mistake. Configure your editor to show invisible characters when editing Makefiles.


Practical Example — Makefile for Python

I start with the most common scenario: a Python project that needs a virtual environment, linting, tests and execution.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# Makefile for a Python project
.PHONY: setup lint test run clean help

PYTHON := python3
VENV := .venv
PIP := $(VENV)/bin/pip
ACTIVATE := . $(VENV)/bin/activate

# Default target — shows help
help:
	@echo "Available targets:"
	@echo "  make setup  - Creates venv and installs dependencies"
	@echo "  make lint   - Runs static analysis (flake8)"
	@echo "  make test   - Runs tests (pytest)"
	@echo "  make run    - Starts the application"
	@echo "  make clean  - Removes venv and caches"

setup: $(VENV)
	$(ACTIVATE) && $(PIP) install -r requirements.txt

$(VENV):
	$(PYTHON) -m venv $(VENV)

lint:
	$(ACTIVATE) && flake8 .

test:
	$(ACTIVATE) && pytest -q

run:
	$(ACTIVATE) && python app.py

clean:
	rm -rf $(VENV) __pycache__ .pytest_cache .mypy_cache

With this Makefile, the workflow becomes simple and predictable:

1
2
3
4
5
6
make setup    # creates the virtual environment and installs dependencies
make lint     # runs static analysis with flake8
make test     # runs tests with pytest
make run      # starts the application
make clean    # cleans temporary files and venv
make help     # shows all available targets

💡 Tip: Always include a help target as the default target (the first one in the file). That way, running make with no arguments shows the documentation of the available commands.


Practical Example — Makefile for Hugo

If you use Hugo to generate static sites — such as a technical blog — you can automate the build, the local server and the deploy with a Makefile.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# Makefile for a Hugo site
.PHONY: serve build deploy clean new help

HUGO := hugo
PUBLIC_DIR := public
DEPLOY_BRANCH := gh-pages

help:
	@echo "Available targets:"
	@echo "  make serve  - Starts local server with drafts"
	@echo "  make build  - Builds optimized site (minified)"
	@echo "  make deploy - Publishes to GitHub Pages"
	@echo "  make new    - Creates a new post (usage: make new TITLE=meu-post)"
	@echo "  make clean  - Removes the public/ folder"

serve:
	$(HUGO) server -D --navigateToChanged

build: clean
	$(HUGO) --minify

deploy: build
	git subtree push --prefix $(PUBLIC_DIR) origin $(DEPLOY_BRANCH)

new:
	$(HUGO) new posts/$(TITLE).md

clean:
	rm -rf $(PUBLIC_DIR)

With this:

1
2
3
4
5
make serve              # starts local server with drafts and live reload
make build              # builds optimized, minified site
make deploy             # runs build + publishes to GitHub Pages
make new TITLE=meu-post # creates a new post from the archetype
make clean              # removes the generated public/ folder

Note that deploy depends on build, which depends on clean. make resolves the chain automatically — you only need to run make deploy and all previous steps run in the correct order.


Practical Example — Makefile for Docker

For container projects, the Makefile removes the need to remember Docker and Docker Compose flags and parameters.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# Makefile for Docker
.PHONY: build up down logs clean shell help

IMAGE_NAME := minhaapp
IMAGE_TAG := dev
COMPOSE := docker compose

help:
	@echo "Available targets:"
	@echo "  make build  - Builds Docker image"
	@echo "  make up     - Starts containers in background"
	@echo "  make down   - Stops containers"
	@echo "  make logs   - Follows logs in real time"
	@echo "  make shell  - Opens a shell in the container"
	@echo "  make clean  - Removes containers, volumes and cache"

build:
	docker build -t $(IMAGE_NAME):$(IMAGE_TAG) .

up:
	$(COMPOSE) up -d

down:
	$(COMPOSE) down

logs:
	$(COMPOSE) logs -f

shell:
	$(COMPOSE) exec app /bin/bash

clean:
	$(COMPOSE) down -v
	docker system prune -f

Now:

1
2
3
4
5
6
make build   # builds Docker image with tag 'dev'
make up      # starts containers via docker compose
make down    # stops containers
make logs    # follows logs in real time
make shell   # opens an interactive shell in the 'app' container
make clean   # removes volumes and cleans the image cache

📌 Example: Want to use a different image? Just pass the variable in the call: make build IMAGE_NAME=meuapp IMAGE_TAG=v1.2.0. This flexibility makes the Makefile adaptable without editing the file.


Putting It All Together — Multi-Project Makefile

In real projects, it is common to have Python, Hugo and Docker in the same repository. You can create a root Makefile that combines all the automations, using prefixes to organize the targets.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
# Combined Makefile — Python + Hugo + Docker
.PHONY: help py-setup py-test py-lint hugo-serve hugo-build \
        docker-build docker-up docker-down all-build all-clean

PYTHON := python3
VENV := .venv
ACTIVATE := . $(VENV)/bin/activate
COMPOSE := docker compose

# === HELP ===
help:
	@echo "=== Python ==="
	@echo "  make py-setup  - Creates venv and installs deps"
	@echo "  make py-test   - Runs tests"
	@echo "  make py-lint   - Runs linting"
	@echo "=== Hugo ==="
	@echo "  make hugo-serve - Local server"
	@echo "  make hugo-build - Builds minified site"
	@echo "=== Docker ==="
	@echo "  make docker-build - Builds image"
	@echo "  make docker-up    - Starts containers"
	@echo "  make docker-down  - Stops containers"
	@echo "=== General ==="
	@echo "  make all-build - Full build (Python + Hugo + Docker)"
	@echo "  make all-clean - Cleans everything"

# === PYTHON ===
py-setup:
	$(PYTHON) -m venv $(VENV)
	$(ACTIVATE) && pip install -r requirements.txt

py-test:
	$(ACTIVATE) && pytest -q

py-lint:
	$(ACTIVATE) && flake8 .

# === HUGO ===
hugo-serve:
	hugo server -D --navigateToChanged

hugo-build:
	hugo --minify

# === DOCKER ===
docker-build:
	docker build -t minhaapp:dev .

docker-up:
	$(COMPOSE) up -d

docker-down:
	$(COMPOSE) down

# === GENERAL ===
all-build: py-setup hugo-build docker-build
	@echo "Full build finished."

all-clean:
	rm -rf $(VENV) __pycache__ public
	$(COMPOSE) down -v
	docker system prune -f

ℹ️ Info: Using prefixes (py-, hugo-, docker-) is a convention that avoids name conflicts and makes targets easy to discover via make help or shell autocompletion.


Tips and Good Practices

After years of using Makefiles in real projects, these are the practices that pay off the most:

  • Always declare .PHONY: without it, targets such as build or test may conflict with files of the same name in the directory, making make silently skip execution.
  • Use variables to avoid repetition: paths, image names, tool versions — anything that appears more than once should become a variable at the top of the file.
  • Make a help target the default: the first target in the Makefile is the default. A well-made help serves as living documentation.
  • Combine it with CI/CD: pipelines can call make test, make build and make deploy, creating a single interface between the local and the automated environments.
  • Document it in the README: list the available targets and their purposes so anyone on the team knows how to use them.
  • Define dependencies between targets: use deploy: build to guarantee the execution order. make takes care of resolving it automatically.
  • Test it in the CI environment: make sure make is available on the build agent. In CI Docker images, you may need to install the build-essential or make package.

⚠️ Warning: Avoid putting complex logic inside the Makefile. If a command has more than 3-4 lines, consider moving it to a separate Bash script and calling it from the Makefile. This improves readability and testability.


Conclusion

The Makefile is a simple but powerful tool that every developer should have in their arsenal. In this article, I showed how it works, built practical examples for Python (setup, lint, tests), Hugo (local server, build, deploy) and Docker (image build, compose, cleanup), and combined everything into a multi-project Makefile.

The big advantage of the Makefile is creating a standardized interface for project operations. Instead of each person on the team remembering different command sequences, everyone uses the same targets — and the same Makefile works both in the local terminal and in CI/CD pipelines.

If you want to go further, explore advanced features such as conditionals (ifeq, ifdef), string functions ($(patsubst ...)) and includes (-include .env) to load variables from a .env file. For projects involving API and token security, also see how to apply security best practices when automating deploys.

Did you like this content? Leave a comment with your favorite Makefile use case, or share this article with someone on your team who still suffers typing commands manually.


Read Also


References