Image by Author | Ideogram# Introduction
Picture this: you’re working on a Python project, and every time you want to run tests, you type python3 -m pytest tests/ --verbose --cov=src. When you want to format your code, it’s black . && isort .. For linting, you run flake8 src tests. Before you know it, you’re juggling a dozen different commands, and your teammates are doing the same thing slightly differently, too.
This is where Makefiles come in handy. Originally used for C and C++ projects, Makefiles can be super useful in Python development as a simple way to standardize and automate common tasks. Think of a Makefile as a single place where you define shortcuts for all the things you do repeatedly.
# Why Use Makefiles in Python Projects?
Consistency Across Your Team
When everyone on your team runs make test instead of remembering the exact pytest command with all its flags, you eliminate the “works on my machine” problem. New team members can jump in and immediately know how to run tests, format code, or deploy the application.
Documentation That Actually Works
Unlike README files that get outdated, Makefiles serve as useful documentation. When someone runs make help, they see exactly what tasks are available and how to use them.
Simplified Complex Workflows
Some tasks require multiple steps. Maybe you need to install dependencies, run migrations, seed test data, and then start your development server. With a Makefile, this becomes a single make dev command.
# Getting Started with Your First Python Makefile
Let’s build a practical Makefile step by step. Create a file named Makefile (no extension) in your project root.
// Basic Structure and Help Command
This code creates an automatic help system for your Makefile that displays all available commands with their descriptions:
.PHONY: help
help: ## Show this help message
@echo "Available commands:"
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-15s\033[0m %s\n", $$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.
