Picture by Writer | Ideogram# Introduction
Image this: you are engaged on a Python mission, and each time you wish to run checks, you sort python3 -m pytest checks/ --verbose --cov=src. While you wish to format your code, it is black . && isort .. For linting, you run flake8 src checks. Earlier than you realize it, you are juggling a dozen completely 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++ initiatives, Makefiles may be tremendous helpful in Python growth as a easy technique 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 Tasks?
Consistency Throughout Your Group
When everybody in your staff runs make check as an alternative of remembering the precise pytest command with all its flags, you remove the “works on my machine” drawback. New staff members can soar in and instantly know the way to run checks, format code, or deploy the appliance.
Documentation That Truly 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. Possibly you could set up dependencies, run migrations, seed check information, 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 mission root.
// Primary Construction and Assist Command
This code creates an automated assist system to your Makefile that shows all out there instructions with their descriptions:
.PHONY: assist
assist: ## Present this assist message
@echo "Accessible instructions:"
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | type | awk 'BEGIN {FS = ":.*?## "}; {printf " 33[36m%-15s 33[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.
