How to Run Makdi on Mac and Linux

Makdi ships as a one-click installer for Windows — but the crawler itself is plain Python, so it runs just as well on macOS and Linux. Here is the full setup, from a blank terminal to your first crawl, in about five minutes.

What you need before you start

Makdi is a local web app. It runs a small server on your own machine, crawls the site you point it at, and shows the results in your browser. Nothing is uploaded anywhere, and no account is required. To run it from source you need three things:

• Python 3.9 or newer — macOS ships with a system Python, but you will install your own (explained below). Most Linux distributions already have a usable one.
• A terminal — Terminal.app on macOS, or GNOME Terminal / Konsole / whatever your distro uses.
• About 60 MB of disk space for the code and its dependencies.

Step 1 — Install Python 3

First check whether you already have it. Open your terminal and run:

python3 --version

If you see Python 3.9.x or higher, skip ahead to Step 2. If you get “command not found” or a version starting with 2, install it.

On macOS

The cleanest route is Homebrew. If you do not have Homebrew yet, install it first with the one-line command on its homepage, then:

brew install python

No Homebrew and no interest in it? Download the official installer from python.org/downloads and run the .pkg — it works fine and puts python3 on your path. This works on both Apple Silicon (M1 through M4) and older Intel Macs.

On Ubuntu, Debian, Linux Mint or Pop!_OS

sudo apt update
sudo apt install python3 python3-pip python3-venv git

On Fedora, RHEL or CentOS

sudo dnf install python3 python3-pip git

On Arch or Manjaro

sudo pacman -S python python-pip git

Step 2 — Get Makdi from GitHub

The full source lives at github.com/disalevikas/makdi under an MIT licence — free for personal and commercial use, and you can read every line before you run it. There are two ways to get it.

Option A — Git clone (recommended)

This makes updating later a single command. Run:

cd ~
git clone https://github.com/disalevikas/makdi.git
cd makdi

Option B — Download the ZIP

If you would rather avoid Git: open the repository page, click the green Code button, choose Download ZIP, and unzip it. Then move into the folder in your terminal — on macOS you can type cd (with the trailing space) and drag the unzipped folder onto the terminal window to fill in the path automatically.

Step 3 — Install the four packages

Makdi depends on four well-known libraries: requests for fetching, beautifulsoup4 and lxml for parsing HTML, and openpyxl for the Excel export.

Install them inside a virtual environment. This keeps them isolated from your system Python and avoids the “externally-managed-environment” error that newer Ubuntu and Homebrew setups throw:

python3 -m venv venv
source venv/bin/activate
pip install requests beautifulsoup4 lxml openpyxl

Your prompt now shows (venv) at the start, meaning the environment is active. You will run that source venv/bin/activate line each time you open a fresh terminal to use Makdi — or skip it entirely with the launcher in the one-click section below.

Step 4 — Run Makdi

From inside the makdi folder, with the venv active:

python3 makdi.py

The terminal prints a startup line and Makdi is now serving on your machine. Open your browser and go to:

http://localhost:8090

You will see the same interface Windows users get — the tab bar, the dashboard, the crawl box. Leave the terminal window open while you work; closing it stops the crawler. To stop it deliberately, press Ctrl + C in the terminal.

Step 5 — Your first crawl

Point it at your own site before you point it at a client’s. Paste the homepage URL into the crawl box, set a crawl limit if you want a quick sample rather than a full sweep, and start it.

1. Watch the Dashboard. You get a 0–100 health score and 28 severity-ranked checks, ordered so the expensive problems sit at the top.
2. Work the tabs left to right. Response codes first (broken links and redirect chains), then titles and meta descriptions, then H1s, canonicals and images.
3. Open the URL detail panel on any row to see inlinks with their anchor text, outlinks with status codes, images and resources for that single page.
4. Check Internal Link Suggestions. This finds unlinked mentions of your target phrases across the site and hands you ready-made anchor text — usually the fastest ranking win in the whole report.
5. Export. Excel action plan, printable PDF report, or CSV from any individual view.

Crawl again next month and the Changes tab will diff the two crawls for you — what broke, what got fixed.

Make it a one-click launcher

Typing three commands every time gets old. Here are two ways around it.

A terminal alias (Mac and Linux)

Open your shell config — ~/.zshrc on modern macOS, ~/.bashrc on most Linux setups — and add this line at the bottom, adjusting the path if you cloned somewhere other than your home folder:

alias makdi="cd ~/makdi && source venv/bin/activate && python3 makdi.py"

Save, then run source ~/.zshrc once. From now on, typing makdi in any terminal starts the crawler.

A double-clickable file on macOS

Create a file called Makdi.command on your Desktop containing:

#!/bin/bash
cd ~/makdi
source venv/bin/activate
python3 makdi.py

Then make it executable and it becomes a double-click launcher:

chmod +x ~/Desktop/Makdi.command

The first double-click may show a Gatekeeper warning because the file is unsigned — right-click the file and choose Open once, and macOS remembers your choice.

Troubleshooting the common errors

What you see	What to do
command not found: python3	Python is not installed or not on your path. Go back to Step 1. On macOS, restarting the terminal after a Homebrew install usually fixes the path.
error: externally-managed-environment	Your OS is protecting the system Python. Use the virtual environment in Step 3 — this is exactly the case it solves.
ModuleNotFoundError: No module named 'bs4'	The packages were installed into a different Python than the one running the script. Activate the venv (source venv/bin/activate) and re-run the pip line.
Failed building wheel for lxml	Missing build headers. On Debian/Ubuntu run sudo apt install libxml2-dev libxslt1-dev python3-dev, then retry. On macOS, xcode-select --install.
Address already in use	Makdi is already running in another terminal, or something else holds port 8090. Close the other window, or find it with lsof -i :8090.
Browser shows “can’t connect”	The script is not running, or it stopped with an error. Check the terminal window for the traceback before anything else.
Crawl returns almost nothing	Usually robots.txt blocking, a login wall, or a JavaScript-rendered site. Makdi respects robots.txt by default — check whether your staging site disallows everything.

Updating to a new version

If you cloned with Git, updating is one command from inside the folder:

cd ~/makdi
git pull

If a release adds a new dependency, re-run the pip install line from Step 3 afterwards. Downloaded the ZIP instead? Grab the new ZIP and replace the folder — your saved crawls live in the app’s data folder, not in the code folder, so they survive.

Frequently asked questions

Is there a native Mac app or .dmg for Makdi?

Not currently. Distributing a Mac app means an Apple Developer account and notarisation for every release, which a free tool cannot sustain. Running from source takes about five minutes once and gives you the identical crawler with every feature the Windows build has.

Does Makdi work on Apple Silicon Macs?

Yes. It is pure Python with no architecture-specific binaries, so M1, M2, M3 and M4 Macs run it natively without Rosetta.

Is the Mac and Linux version limited compared to Windows?

No. The Windows installer simply wraps the same makdi.py in a native window. All 16 analysis tabs, the dashboard scoring, internal link suggestions, crawl comparison, and the Excel and PDF exports are identical.

Is there a URL limit?

No. Makdi will crawl as many URLs as your machine’s memory allows. Very large sites are best crawled in sections, but there is no artificial cap.

Does Makdi send my crawl data anywhere?

No. The crawler runs entirely on your own machine and stores results locally. There is no account, no cloud sync, and no telemetry. Makdi identifies itself to the sites it crawls with the MakdiBot user agent.

Do I need to know Python to use it?

No. You copy and paste a handful of commands once during setup. After that, everything happens in a normal browser interface — the terminal just sits in the background.