Skip to main content

Installing Sweepy

You need three things on your computer before you can run Sweepy:

  1. Python: the programming language that powers the engine.
  2. Git: a tool that downloads the engine's code from the internet.
  3. pip: a package manager that installs the extra libraries the engine needs. The official installers for Windows and macOS include pip. Linux distributions add pip through the system package manager.
note

This guide walks through every step for someone who has never opened a terminal before. If you already have Python 3.10+ and Git installed, skip ahead to Step 3.

Step 1: Open your terminal​

A terminal, also called a command prompt, is a text-based window where you type commands. You type instructions to your computer here instead of selecting icons.

Press the Windows key, type PowerShell, then select Windows PowerShell.

Terminal
Windows PowerShell
Copyright (C) Microsoft Corporation. All rights reserved.

PS C:\Users\YourName>

The prompt ends with a blinking cursor. That cursor means your terminal sits ready for a command.

Step 2: Check and install Python​

Sweepy requires Python 3.10 or newer. Check if you already have it.

Type this command in your terminal and press Enter:

Terminal
python --version

On macOS and Linux, the command is python3 --version.

If you see Python 3.10.x or higher, you already have Python. Skip to Step 3.

If you see an error message like 'python' is not recognized or a version below 3.10, follow the installation steps below.

  1. Visit the Python downloads page for Windows.
  2. Select the newest Windows installer (64-bit) download link.
  3. Run the downloaded file.
  4. This step is critical. On the first screen of the installer, select the checkbox labeled "Add python.exe to PATH" at the bottom. The checkbox puts Python on your PATH, where the terminal can find it.
  5. Select Install Now and wait for the installation to finish.

Then confirm the install in a fresh terminal window:

Terminal
PS C:\Users\YourName> python --version
Python 3.13.1
caution

If you skip "Add python.exe to PATH," your terminal won't recognize the python command. Uninstall Python, then reinstall it with the box selected.

The Windows, macOS, and Linux tabs end with the same check. Close your terminal, open it again, and run the version command. A version number of 3.10 or higher means Python is ready.

Step 3: Download Sweepy​

Downloading Sweepy's source files

Pick one method. Use Git, described below, or download a ZIP file from the Sweepy release page.

Git copies the project files to your computer and records their history. That history lets Sweepy update itself. The steps below use Git.

  • Git copy. Run sweepy --update or the Toolbox updater to pull each new release.
  • ZIP copy. Download, unzip, and run pip install -e . again for every release. Automatic updates stay off, because a ZIP has no Git history to pull from.
  • Folder name. Git creates a folder called sweepy. A ZIP unpacks into a folder such as sweepy-main, so adjust the cd command later in this step.

Choose the ZIP for a one-time look. Choose Git if you plan to keep using Sweepy.

First, check if Git is already installed:

Terminal
git --version

If you see a version number such as git version 2.45.1, you have Git.

If you see an error, install Git:

  1. Visit git-scm.com/download/win.
  2. Download and run the installer.
  3. Accept all default settings and select Install.
  4. Close and reopen your terminal, then confirm:
Terminal
PS C:\Users\YourName> git --version
git version 2.45.1

Now, download Sweepy by running:

Terminal
git clone https://github.com/pvega62/sweepy.git

This creates a new folder called sweepy on your computer. Navigate into it:

Terminal
cd sweepy
tip

Git puts the new folder in whatever directory your terminal pointed at when you ran the command. On Windows, a fresh PowerShell window starts in C:\Users\YourName\.

Step 4: Install dependencies​

Sweepy relies on a few extra libraries to work:

  • pymupdf: reads and extracts text from your resume PDF.
  • python-docx: reads and converts .docx resumes.
  • python-jobspy: scrapes job boards securely without requiring an API key.
  • beautifulsoup4: parses HTML from the Greenhouse, Lever, Workable, and Built In sources.
  • reportlab: generates the styled PDF report with clickable links.
  • requests: sends web requests to check if URLs are still active.
  • pyyaml & questionary: handle the interactive configuration wizard. prompt-toolkit supplies its keyboard controls.
  • pandas: structures scraped job data and builds CSV spreadsheet exports.
  • mcp & anyio: run the optional Model Context Protocol server that connects Sweepy to an AI assistant.
Python 3.13

If you use Python 3.13, install the Microsoft C++ Build Tools first and select the "Desktop development with C++" workload. Python 3.13 is new enough that some packages, such as pymupdf, may compile from source and require those tools. Skip this step on Python 3.12 or older.

Sweepy's automated tests cover Python 3.10 through 3.12. Those versions stay the smoothest path.

Install every package with one command:

Terminal
pip install -e .

That command installs every dependency and registers a sweepy command in your Python Scripts folder. Reopen your terminal once so PATH picks up the new folder. From then on, run sweepy --run instead of python swee.py --run. Run either form from your sweepy folder.

Text scrolls by as Python downloads and installs each package. When the cursor returns, installation is complete.

tip

Did you get a "command not found" error for pip? Try pip3 install -e . instead. On some systems, Python 3 uses pip3 as the command name.

Verify your installation​

Run this quick check to confirm everything installed correctly:

Terminal
sweepy --version

If your shell can't find sweepy, reopen the terminal or run python swee.py --version instead. You'll see:

Terminal output
Sweepy v3.0.0
Python 3.13.1 | pymupdf 1.28.2 | reportlab 5.0.1
Ready to sweep.

If that message appears, Sweepy's ready. Expect different numbers on your machine. Sweepy prints the release from its VERSION file, and pip installs packages that match your Python version.

The second line reports the pymupdf and reportlab versions.

Next, configure your personalized job search profile.