Skip to main content

A containerized version of Valgrind for OSX.

Project description


CI Stable version Latest version

Containerized Valgrind on macOS for C and C++ projects.


As of the time of writing this, Valgrind is not natively supported on several recent versions of macOS. This tool allows you to run it in a Docker container without any code changes or extra garbage.

how to install

You can install macgrind via pip:

$ pip3 install macgrind

You also need to install Docker Desktop, and have it running.

how to use

You can use macgrind by specifying the project's directory, and a target binary to run valgrind on. Please note that the target binary's path must be the one relative to the project path instead of the absolute one.

For example, say I have a C project with the following structure:


I need to supply the full path to my_c_project/, but only the relative path to the target executable: main (and not my_c_project/main). The assumption here is that the all target in the Makefile builds my_c_project/main.

So, we could run macgrind like this:

$ macgrind my_c_project/ main
Creating temporary Dockerfile...
Building Docker image...
Running Docker container...
Here's the output of the container:
==1== Memcheck, a memory error detector
==1== Copyright (C) 2002-2017, and GNU GPL'd, by Julian Seward et al.
==1== Using Valgrind-3.13.0 and LibVEX; rerun with -h for copyright info
==1== Command: /valgrind_project_tmp/main
Hello, World!
==1==     in use at exit: 0 bytes in 0 blocks
==1==   total heap usage: 2 allocs, 2 frees, 4,196 bytes allocated
==1== All heap blocks were freed -- no leaks are possible
==1== For counts of detected and suppressed errors, rerun with: -v
==1== ERROR SUMMARY: 0 errors from 0 contexts (suppressed: 0 from 0)
Container exited without errors (exit code: 0)

By default, macgrind will build a Docker image based on ubuntu:18.04. It will then build your project by running make all in the project directory, then run the target using valgrind --leak-check=full --error-exitcode=1 <target>.

more options

You can specify the image on which the container will be built by running macgrind with the -i (or --image) option:

$ macgrind my_c_project/ main --image ubuntu:16.04

Very often, projects depend on additional libraries. You can specify dependencies to be installed with apt-get using the -d (or --dependencies) option:

$ macgrind my_curl_c_project/ main --dependencies libcurl4-openssl-dev

If you wish to run a custom command to build your project or just one target, other than make all, you can specify it using the -c (or --custom-command) option. Be aware, as with the executable, the custom command must assume a relative address, as it will be run inside of your project directory:

$ macgrind my_c_project/ main --custom-command "gcc src/main.c -o main"

To get the full option list, run:

$ macgrind --help

how it works

I've written a small blogpost about it.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

macgrind-1.0.4.tar.gz (5.7 kB view hashes)

Uploaded source

Built Distribution

macgrind-1.0.4-py3-none-any.whl (18.8 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page