The Case for Makefiles in Python Initiatives (And Easy methods to Get Began)

Picture by Creator | Ideogram

# Introduction

 
Image this: you are engaged on a Python undertaking, and each time you wish to run exams, you kind python3 -m pytest exams/ --verbose --cov=src. Whenever you wish to format your code, it is black . && isort .. For linting, you run flake8 src exams. Earlier than you realize it, you are juggling a dozen totally different instructions, and your teammates are doing the identical factor barely in another way, too.

That is the place Makefiles come in useful. Initially used for C and C++ tasks, Makefiles will be tremendous helpful in Python growth as a easy strategy to standardize and automate widespread duties. Consider a Makefile as a single place the place you outline shortcuts for all of the belongings you do repeatedly.

# Why Use Makefiles in Python Initiatives?

 
Consistency Throughout Your Group
When everybody in your crew runs make take a look at as a substitute of remembering the precise pytest command with all its flags, you get rid of the “works on my machine” downside. New crew members can bounce in and instantly know the way to run exams, format code, or deploy the applying.

Documentation That Really Works
Not like README recordsdata that get outdated, Makefiles function helpful documentation. When somebody runs make assist, they see precisely what duties can be found and the way to use them.

 
Simplified Advanced Workflows
Some duties require a number of steps. Perhaps you could set up dependencies, run migrations, seed take a look at knowledge, after which begin your growth server. With a Makefile, this turns into a single make dev command.

# Getting Began with Your First Python Makefile

 
Let’s construct a sensible Makefile step-by-step. Create a file named Makefile (no extension) in your undertaking root.
 

// Fundamental Construction and Assist Command

This code creates an automated assist system to your Makefile that shows all accessible instructions with their descriptions:

.PHONY: assist
assist:  ## Present this assist message
	@echo "Accessible instructions:"
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | kind | awk 'BEGIN {FS = ":.*?## "}; {printf "  33[36m%-15s33[0m %sn", $$1, $$2}'

.DEFAULT_GOAL := help

The .PHONY: help tells Make that “help” isn’t a real file but a command to run. When you type make help, it first prints “Available commands:” then uses a combination of grep and awk to scan through the Makefile itself, find all lines that have command names followed by ## description, and format them into a nice readable list with command names and their explanations.

// Environment Setup

This code creates three environment management commands:

.PHONY: install
install:  ## Install dependencies
	pip install -r requirements.txt
	pip install -r requirements-dev.txt

.PHONY: venv
venv:  ## Create virtual environment
	python3 -m venv venv
	@echo "Activate with: source venv/bin/activate"

.PHONY: clean
clean:  ## Clean up cache files and build artifacts
	find . -type f -name "*.pyc" -delete
	find . -type d -name "__pycache__" -delete
	find . -type d -name "*.egg-info" -exec rm -rf {} +
	rm -rf build/ dist/ .coverage htmlcov/ .pytest_cache/

The install command runs pip twice to install both main dependencies and development tools from requirements files. The venv command creates a new Python virtual environment folder called “venv” and prints instructions on how to activate it.

The clean command removes all the messy files Python creates during development. It deletes compiled Python files (.pyc), cache folders (pycache), package info directories, and build artifacts like coverage reports and test caches.

// Code Quality and Testing

This creates code quality commands:

.PHONY: format
format:  ## Format code with black and isort
	black .
	isort .

.PHONY: lint
lint:  ## Run linting checks
	flake8 src tests
	black --check .
	isort --check-only .

.PHONY: test
test:  ## Run tests
	python -m pytest tests/ --verbose

.PHONY: test-cov
test-cov:  ## Run tests with coverage
	python -m pytest tests/ --verbose --cov=src --cov-report=html --cov-report=term

.PHONY: check
check: lint test  ## Run all checks (lint + test)

The format command automatically fixes your code style using black for formatting and isort for import organization.

The lint command checks if your code follows style rules without changing anything. flake8 finds style violations, while black and isort run in check-only mode to see if formatting is needed.

The test command runs the test suite. test-cov runs tests and also measures code coverage and generates reports. The check command runs both linting and testing together by depending on the lint and test commands.

// Development Workflow

This creates development workflow commands:

.PHONY: dev
dev: install  ## Set up development environment
	@echo "Development environment ready!"
	@echo "Run 'make serve' to start the development server"

.PHONY: serve
serve:  ## Start development server
	python3 -m flask run --debug

.PHONY: shell
shell:  ## Start Python shell with app context
	python3 -c "from src.app import create_app; app=create_app(); app.app_context().push(); import IPython; IPython.start_ipython()"

The dev command first runs the install command to set up dependencies, then prints success messages with next steps. The serve command starts a Flask development server in debug mode.

The shell command launches an IPython shell that’s already connected to your Flask app context, so you can test database queries and app functions interactively without manually importing everything.

# More Makefile Techniques

// Using Variables

You can define variables to avoid repetition:

PYTHON := python3
TEST_PATH := tests/
SRC_PATH := src/

.PHONY: test
test:  ## Run tests
	$(PYTHON) -m pytest $(TEST_PATH) --verbose

// Conditional Commands

Sometimes you want different behavior based on the environment:

.PHONY: deploy
deploy:  ## Deploy application
ifeq ($(ENV),production)
	@echo "Deploying to production..."
	# Production deployment commands
else
	@echo "Deploying to staging..."
	# Staging deployment commands
endif

// File Dependencies

You can make targets depend on files, so they only run when needed:

requirements.txt: pyproject.toml
	pip-compile pyproject.toml

.PHONY: sync-deps
sync-deps: requirements.txt  ## Sync dependencies
	pip-sync requirements.txt

🔗 Here’s an example of a complete Makefile for a Flask web application.

# Best Practices and Tips

 
Here are some best practices to follow when writing Makefiles:

• Don’t overcomplicate your Makefile. If a task is getting complex, consider moving the logic to a separate script and calling it from Make.
• Choose command names that clearly indicate what they do. make test is better than make t, and make dev-setup is clearer than make setup.
• For commands that don’t create files, always declare them as .PHONY. This prevents issues if someone creates a file with the same name as your command.
• Organize your Makefiles to group related functionality together.
• Make sure all your commands work from a fresh clone of your repository. Nothing frustrates new contributors like a broken setup process.

# Conclusion

 
Makefiles might seem like an old-school tool, but they’re effective for Python projects. They provide a consistent interface for common tasks and help new contributors get productive quickly.

Create a basic Makefile with just install, test, and help commands. As your project grows and your workflow becomes more complex, you can add more targets and dependencies as needed.

Remember, the goal isn’t to create the most clever or complex Makefile possible. It’s to make your daily development tasks easier and more reliable. Keep it simple, keep it useful, and let your Makefile become the command center that brings order to your Python project chaos.
 
 

Bala Priya C is a developer and technical writer from India. She likes working at the intersection of math, programming, data science, and content creation. Her areas of interest and expertise include DevOps, data science, and natural language processing. She enjoys reading, writing, coding, and coffee! Currently, she’s working on learning and sharing her knowledge with the developer community by authoring tutorials, how-to guides, opinion pieces, and more. Bala also creates engaging resource overviews and coding tutorials.