A Makefile to be used for automating Python development operations.
Makefiles are not only useful for C or C++. You can use them for pretty much everything. In this case, instead of writing complex commands by hand or using a shell script, I use a Makefile to run complex operations in my Python projects.
- setup and remove a development environment using venv
- lock requirements with hashes to make the development and production environments partially reproducible
- run tests, benchmarks, fuzzer and demo
- build package (wheel and dist) in Docker, using reproducible instructions
- upload to PyPI
- build documentation
- setup, update and run pre-commit hooks
- cleanup
- no AI features, no hallucinations, no tokens, no costs
Those are non standard built-in tools:
- uv is now owned by OpenAI so it's dangerous in terms of vendor lock-in and possible rug-pulls
- Pipenv had huge problems during the lock file phase; that was the first reason I stopped using it years ago
- Poetry is complex, as stated in
their readme
Poetry is a large, complex project always in need of contributors
Once pylock.toml goes mainstream, this Makefile will be even simpler, possibily only requiring built-in Python tools except from pip-audit.
python-makefile tries to use as much standard tools as possible, and prepares a workflow for you
Note
hatch uses uv so build or hatchling are the preferred build backend tools instead. See also How to create a pylock.toml lockfile.
After setting up python-makefile once for your project, all you have to do is:
make regenerate-dev-lock
make regenerate-lock
make install-devThese commands create dependency lock files and an up-to-date virtual
environment in .venv/.
| Command | Description | Can override | Makefile override variable |
|---|---|---|---|
make benchmark |
Run some benchmarks. Must be ${PYTHON_MODULE_NAME}/tests/benchmark.py |
✘ | |
make clean |
Clean temporary files | ✓ | OVERRIDE_CLEAN |
make doc |
Build the documentation with sphinx | ✓ | OVERRIDE_DOC |
make demo |
Run a CLI demo to show how the project works. Uses asciinema | ✘ | |
make dist |
Create reproducible wheel and source distributions ready for PyPI, as well as their checksums | ✘ | |
make fuzzer |
Run a fuzzer. Must be ${PYTHON_MODULE_NAME}/tests/fuzzer.py |
✘ | |
make install-dev |
Install the development environment | ✓ | OVERRIDE_INSTALL_DEV |
make pre-commit |
Run all pre-commit hooks | ✘ | |
make pre-commit-update |
Update pre-commit hooks | ✓ | OVERRIDE_UPDATE |
make regenerate-lock |
Pin and checksum Python production requirements in a file | ✓ | OVERRIDE_REGENERATE_LOCK |
make regenerate-dev-lock |
Pin and checksum Python development requirements in a file | ✓ | OVERRIDE_REGENERATE_DEV_LOCK |
make test |
Run unit tests for all Python versions defined in ./setup.cfg. Must be in ${PYTHON_MODULE_NAME}/tests/tests.py |
✘ | |
make test-single |
Run unit tests for the default Python version. Must be in ${PYTHON_MODULE_NAME}/tests/tests.py |
✘ | |
make upload |
Upload the distribution files generated with make dist to PyPI |
✘ | |
make uninstall-dev |
Remove the development environment | ✓ | OVERRIDE_UNINSTALL_DEV |
-
install curl and make. On Debian-based systems:
apt install curl make
-
download the
.project.mkfile in your repositorycurl -o .project.mk https://github.com/frnmst/python-makefile/raw/branch/master/.project.linux.mk.example
In the example file md-toc is used as project: the name of the project is
md-toc(hyphen) but the Python module is calledmd_toc(underscore). That is why there are two variables. -
add
Makefileto your gitignoreecho 'Makefile' >> .gitignore
-
download the Makefile in your project. The follwing also pulls new updates from this repository if there have been changes in the Makefile:
make -f .project.mk bootstrap
-
If you are bootstrapping a new project from scratch, regenerate the requirements lock files. You might want to do this again when updates or dependency changes are required:
make regenerate-dev-lock make regenerate-lock
-
install the development environment from the lock file. Your project must have a
pyproject.tomlfile:make install-dev
If you clone a project that uses python-makefile this is essentially all you have to do
To mitigate supply chain attacks, as suggested by
this PyPI blog post, dependency cooldown was added in python-makefile 0.3.0 via the
--uploaded-prior-to pip option.
You can also create new custom targets in
.project.mk and run them
make example-targetSimilarly, overriding is just as simple: just add your overridden target and
the override variable in the .project.mk file.
Remember that .project.mk is Git tracked while Makefile is not.
To deterministically build your Python project inside a Docker container, run:
sudo make distThis also generates checksums for the wheel and source distributions.
Some of my Python projects contain a ./safe_install.sh script that checks the
signed shell commands against my public GPG key and compares local hashes with
the ones available on PyPI. Follow the instructions on respective project
readmes.
MIT License
Copyright (C) 2024-2026 Franco Masotti (see /README.md)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
| URL | Type | Notes |
|---|---|---|
| https://github.com/frnmst/python-makefile | RW | Official home |
| https://codeberg.org/frnmst/python-makefile | RW | Mirror |
| https://framagit.org/frnmst/python-makefile | RW | Mirror |
| https://repos.franco.net.eu.org/frnmst/python-makefile | RW | Mirror |