Quick answer: Most SpiderFoot errors come from four things: installing outside a Python virtual environment, a Python version that is too new for SpiderFoot’s pinned libraries, a busy port, or missing API keys. Create a venv, install requirements.txt inside it, start SpiderFoot on a free port with python3 sf.py -l 127.0.0.1:5001, and add API keys in Settings. If a library still will not build, use Docker or the Kali package.
This guide lists the SpiderFoot errors people hit most often in 2026, explains what each message means in plain English, and gives you the exact fix. Scroll to your section, or press Ctrl + F and paste your error message.
Before You Start: 3 Quick Checks
- Check your Python version:
python3 --version. SpiderFoot 4.0 needs Python 3.7 or newer. Very new versions (3.12, 3.13 and later) can fail to build some of its older pinned libraries. - Check you are in the SpiderFoot folder:
lsshould showsf.pyandrequirements.txt. - Turn on debug output: start SpiderFoot with
python3 sf.py -d -l 127.0.0.1:5001. The extra logging usually points straight at the problem. Scan-level logs are also in the Log tab of every scan.
Installation Errors
1. error: externally-managed-environment
What it means: Newer Linux systems (Kali, Debian 12+, Ubuntu 23.04+) block pip from installing packages system-wide.
Fix: Install SpiderFoot inside a virtual environment:
cd spiderfoot
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip wheel setuptools
pip install -r requirements.txtOn Kali you can skip pip completely with sudo apt install spiderfoot. See our SpiderFoot Kali Linux install guide.
2. Failed building wheel for lxml
What it means: SpiderFoot pins lxml below version 5. On new Python versions there may be no ready-made wheel, so pip tries to compile it and fails.
Fix (pick one):
- Install the build headers:
sudo apt install libxml2-dev libxslt1-dev python3-dev build-essential(Debian/Ubuntu/Kali). - Create the venv with an older, supported Python such as 3.11 (for example with
pyenvoruv). - Run SpiderFoot in Docker, which ships its own tested Python.
3. Failed building wheel for cryptography
What it means: The pinned cryptography version could not find a prebuilt wheel for your platform (common on ARM, Android/Termux and some Macs).
Fix: Install Rust and OpenSSL headers (sudo apt install rustc cargo libssl-dev libffi-dev), upgrade pip, and retry. On Termux use pkg install rust openssl libffi, or follow Method 2 in our SpiderFoot Termux guide.
4. ModuleNotFoundError: No module named ‘distutils’
What it means: Python 3.12 removed distutils, which some older packages still import.
Fix: pip install --upgrade setuptools inside your venv. If it persists, use Python 3.11 or Docker.
5. Microsoft Visual C++ 14.0 or greater is required (Windows)
What it means: pip needs a C compiler to build a package on Windows.
Fix: Install “Build Tools for Visual Studio” with the Desktop development with C++ workload, then rerun pip install -r requirements.txt. Or use Docker Desktop or WSL. Our SpiderFoot install guide for Windows, Mac, Linux and Docker walks through each option.
6. ‘python’ is not recognized as an internal or external command
Fix: Reinstall Python from python.org and tick Add python.exe to PATH, or use the launcher: py -3 sf.py -l 127.0.0.1:5001.
Startup Errors
7. ModuleNotFoundError: No module named ‘cherrypy’ (or ‘mako’, ‘dns’, ‘yaml’)
What it means: The requirements are not installed in the Python you are using. This almost always happens because the venv is not active.
Fix: Run source venv/bin/activate (Linux/macOS) or venv\Scripts\activate (Windows), then pip install -r requirements.txt and start SpiderFoot again.
8. SyntaxError when running sf.py
What it means: You started SpiderFoot with Python 2.
Fix: Always use python3 sf.py. Python 2 is not supported.
9. OSError: [Errno 98] Address already in use
What it means: Something is already using port 5001, often an older SpiderFoot process.
Fix: Use another port (python3 sf.py -l 127.0.0.1:5002) or find and stop the old process:
sudo lsof -i :5001
kill PID_NUMBEROn Windows use netstat -ano | findstr 5001 and end the task in Task Manager.
10. Web UI will not load (“This site can’t be reached”)
- Make sure the terminal running SpiderFoot is still open.
- Use
http://, nothttps://. - If you access it from another device, start it with
-l 0.0.0.0:5001and allow the port in your firewall. - With Docker, confirm the port mapping:
docker run -p 5001:5001 ...
11. Permission denied or “database is locked”
What it means: SpiderFoot cannot write its SQLite database, or two SpiderFoot instances are using the same database.
Fix: Run only one instance at a time, and make sure your user owns SpiderFoot’s data folder (by default ~/.spiderfoot on Linux). Avoid running it with sudo unless you installed it that way.
Scan and Module Errors
12. Scan stuck on “RUNNING” or “STARTING”
Fix: Open the scan’s Log tab to see which module is hanging. Abort the scan, then rerun with the Passive or Footprint profile, or deselect slow modules. Lowering the maximum threads in Settings also helps on small machines.
13. A module returns no data
- The module needs an API key. Add it under Settings and click Save Changes.
- The key hit its daily limit (HTTP 429). Wait, or upgrade the plan.
- The target type does not match the module. Learn which target types SpiderFoot can analyze.
Our list of SpiderFoot modules and data sources shows which ones need keys.
14. SSL: CERTIFICATE_VERIFY_FAILED
Fix: Update your certificate store: sudo apt install --reinstall ca-certificates on Linux, or run Install Certificates.command from your Python folder on macOS. Inside the venv, pip install --upgrade certifi. Corporate proxies that inspect HTTPS can also cause this.
15. Tor / dark web modules fail
Fix: Install and start Tor (sudo apt install tor && sudo systemctl start tor), then in Settings set the SOCKS proxy to 127.0.0.1 port 9050 with type TOR.
16. Scan is very slow or uses too much memory
Fix: Avoid the All profile for large targets, limit subdomain brute-forcing, reduce threads, and delete old scans you no longer need to keep the database small.
Error Quick-Reference Table
| Error | Most likely cause | Fastest fix |
|---|---|---|
| externally-managed-environment | System pip blocked | Use a venv |
| Failed building wheel for lxml | Python too new / missing headers | Install libxml2-dev, libxslt1-dev or use Python 3.11 |
| Failed building wheel for cryptography | No wheel for platform | Install Rust + libssl-dev |
| No module named ‘cherrypy’ | venv not active | Activate venv, reinstall requirements |
| Address already in use | Port 5001 busy | Use port 5002 or stop old process |
| Site can’t be reached | Server stopped / wrong URL | Keep terminal open, use http:// |
| database is locked | Two instances running | Run one instance only |
| Module returns nothing | Missing or rate-limited API key | Add or check key in Settings |
How to Do a Clean Reinstall
If nothing works, start fresh. Back up your data folder first if you want to keep old scans.
rm -rf spiderfoot
git clone https://github.com/smicallef/spiderfoot.git
cd spiderfoot
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip wheel setuptools
pip install -r requirements.txt
python3 sf.py -l 127.0.0.1:5001Still stuck? Search the SpiderFoot GitHub issues for your exact error message. Include your OS, Python version and the full error text if you open a new issue.
Frequently Asked Questions
Why won’t SpiderFoot install on Python 3.12 or 3.13?
SpiderFoot 4.0 pins older versions of libraries such as lxml. On very new Python versions pip may have to compile them and fail. Install the build headers, use Python 3.11 in a virtual environment, or run SpiderFoot in Docker.
How do I fix ‘No module named cherrypy’ in SpiderFoot?
Activate the virtual environment you created for SpiderFoot, then run pip install -r requirements.txt from the SpiderFoot folder. The error means the requirements are not installed in the Python you are using.
How do I change the SpiderFoot port?
Start SpiderFoot with a different port in the -l option, for example python3 sf.py -l 127.0.0.1:5002, then open http://127.0.0.1:5002.
Where are SpiderFoot logs stored?
Each scan has a Log tab in the web interface. You can also start SpiderFoot with -d for debug output in the terminal. On Linux, SpiderFoot keeps its database and logs in the ~/.spiderfoot data folder by default.
Why does my SpiderFoot scan return no results?
Common reasons are missing or rate-limited API keys, a scan profile that skips the modules you need, or a target type the modules do not support. Check the scan Log tab to see which modules ran.
Is Docker the easiest way to avoid SpiderFoot errors?
Often, yes. Docker builds SpiderFoot with a tested Python version and its own libraries, so most dependency and Python version errors disappear.
Conclusion
Nearly every SpiderFoot problem can be fixed in a few minutes: use a virtual environment, stay on a Python version the pinned libraries support (or use Docker), pick a free port, and add API keys for the modules you rely on. Once it is running, learn the tool properly with our SpiderFoot tutorial for beginners and our SpiderFoot commands guide.
Pingback: Does SpiderFoot Need Technical Skills? Answer + 30-Day Plan