Resume-Matcher Documentation

The #1 AI Harness for Building Resumes, PDFs, Cover Letters & more, locally with 100+ LLMs support.

28,111 stars TypeScript TypeScript 1 file ยท ~3,417 tokens #applicant-tracking-system#ats#hacktoberfest#machine-learning#natural-language-processing#nextjs#python#resume
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy Resume-Matcher on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name resume-matcher -p 3000:3000 --restart always ghcr.io/srbhr/resume-matcher
Configured Services & Ports
โš™๏ธ resume-matcher
image: ghcr.io/srbhr/resume-matcher
๐Ÿ”Œ Ports: ${PORT:-3000}:3000
docker-compose.yml
yaml (docker-compose.yml) 
services:
  resume-matcher:
    image: ghcr.io/srbhr/resume-matcher
    build:
      context: .
      # Optional, for slow networks (empty by default = no change):
      #   DEBIAN_MIRROR=https://mirrors.edge.kernel.org/debian docker compose build
      args:
        - DEBIAN_MIRROR=${DEBIAN_MIRROR:-}
        - DEBIAN_SECURITY_MIRROR=${DEBIAN_SECURITY_MIRROR:-}
        - PIP_INDEX_URL=${PIP_INDEX_URL:-}
        - PLAYWRIGHT_DOWNLOAD_HOST=${PLAYWRIGHT_DOWNLOAD_HOST:-}
    container_name: resume-matcher
    ports:
      - "${PORT:-3000}:3000"
    volumes:
      - resume-data:/app/backend/data
    #secrets:
    #  - llm_api_key
    environment:
      # domain in reverse proxy
      - FRONTEND_BASE_URL=${FRONTEND_BASE_URL:-http://localhost:3000}
      # Logging configuration: DEBUG, INFO, WARNING, ERROR
      - LOG_LEVEL=${LOG_LEVEL:-INFO}
      #- LOG_LEVEL_FILE=${LOG_LEVEL_FILE:-}
      # Debug level for LiteLLM: DEBUG, INFO, WARNING, ERROR
      - LOG_LLM=${LOG_LLM:-WARNING}
      #- LOG_LLM_FILE=${LOG_LLM_FILE:-}
      # LLM Configuration - configure via Settings UI or set env vars for explicit overrides
      # Supported providers: openai, anthropic, openrouter, gemini, deepseek, ollama
      # Defaults are defined in apps/backend/app/config.py
      - LLM_PROVIDER=${LLM_PROVIDER:-openai}
      - LLM_MODEL=${LLM_MODEL:-}
      # Optional Docker Secret file path (same behavior as Postgres-style *_FILE)
      #- LLM_API_KEY_FILE=${LLM_API_KEY_FILE:-/run/secrets/llm_api_key}
      - LLM_API_KEY=${LLM_API_KEY:-}
      # For Ollama running on host machine, use host.docker.internal:
      # - LLM_API_BASE=http://host.docker.internal:11434
      - LLM_API_BASE=${LLM_API_BASE:-}
      # CORS origins (JSON array format). FRONTEND_BASE_URL is auto-included.
      #- CORS_ORIGINS=["http://localhost:3000","http://127.0.0.1:3000"]
    restart: unless-stopped
    # Fast iteration: `docker compose watch` (Compose 2.22+). Backend code is synced into
    # the running container and the app restarts; no image rebuild. Frontend, dependency
    # and image changes rebuild the image (Chromium and Python deps stay cached).
    # Plain `docker compose up` ignores this block.
    develop:
      watch:
        - action: sync+restart
          path: ./apps/backend/app
          target: /app/backend/app
          ignore:
            - __pycache__/
        - action: rebuild
          path: ./apps/frontend
          ignore:
            - node_modules/
            - .next/
        - action: rebuild
          path: ./apps/backend/pyproject.toml
        - action: rebuild
          path: ./Dockerfile
        - action: rebuild
          path: ./docker

#secrets:
#  llm_api_key:
#    file: ./secrets/llm_api_key

volumes:
  resume-data:
    driver: local

1. Project Overview & Quickstart (srbhr/Resume-Matcher)

[!IMPORTANT]

The project needs your help and support. If you can donate a small amount, that will help me to continue developing and improving Resume Matcher.

Getting Started

Resume Matcher works by creating a master resume that you can use to tailor for each job application. Installation instructions here: How to Install

How It Works

  1. Upload your master resume (PDF or DOCX)
  2. Paste a job description you're targeting
  3. Review AI-generated improvements and tailored content
  4. Cover Letter and optional interview preparation for the job application
  5. Customize the layout and sections to fit your style
  6. Export as a professional PDF with your preferred template

Stay Connected

Join our Discord for discussions, feature requests, and community support.

Follow us on LinkedIn for updates.

Star the repo to support development and get notified of new releases.

Sponsors

Resume Matcher is free and open-source, kept alive by its sponsors and backers. If it helps you, please consider supporting its development.

Companies backing Resume Matcher

Sponsor at a company tier and your logo + link + blurb lands here โ€” in front of a community of 27k+ stars and 4.9k forks, featured on Trendshift and the Vercel OSS Program.

Sponsor Description
Apideck One API to connect your app to 200+ SaaS platforms (accounting, HRIS, CRM, file storage). Build integrations once, not 50 times. ๐ŸŒ apideck.com
Vercel Resume Matcher is a part of Vercel OSS // Summer 2025 Program ๐ŸŒ vercel.com
Cubic.dev Cubic provides PR reviews for Resume Matcher ๐ŸŒ cubic.dev
Kilo Code Kilo Code provides AI code reviews and coding credits to Resume Matcher ๐ŸŒ kilo.ai
ZanReal ZanReal is an AI-driven development company building scalable cloud solutions, from strategy and UX to DevOps, helping teams ship faster and turn ideas into production. ๐ŸŒ zanreal.com
โœฆ Your company here Reach 27k+ developers and 4.9k forks. Become a sponsor โ†’

Read the Sponsorship Guide for tiers and details. Sponsors get a special thank-you in the README and on our website.

Support as an individual

Every bit keeps Resume Matcher free and funds new features โ€” and you'll be thanked in the README and on our website.

Platform Link
GitHub
Buy Me a Coffee

Creators' Note

Thank you for checking out Resume Matcher. If you want to connect, collaborate, or just say hi, feel free to reach out!
~ Saurabh Rai โœจ

You can follow me on:

Key Features

Core Features

Master Resume: Create a comprehensive master resume to draw from your existing one.

Resume Builder

Paste in a job description and get AI-powered resume tailored for that specific role.

You can:

  • Modify suggested content
  • Add/remove sections
  • Rearrange sections via drag-and-drop
  • Choose from multiple resume templates

Cover Letter Generator

Generate tailored cover letters based on the job description and your resume.

Interview Preparation

Generate structured, resume-grounded interview prep for saved tailored resumes. Use the Builder's Interview Prep tab on demand, or enable automatic generation in Settings.

Resume Scoring & Keyword Highlighting

Analyze your resume against the job description with a match score, keyword highlighting, and suggestions for improvement.

PDF Export

Export your tailored resume and cover letter in PDF.

Templates

Template Name Preview Description
Classic Single Column A traditional and clean layout suitable for most industries. ๐•๐ข๐ž๐ฐ ๐๐ƒ๐…
Modern Single Column A contemporary design with a focus on readability and aesthetics. ๐•๐ข๐ž๐ฐ ๐๐ƒ๐…
Classic Two Column A structured layout that separates sections for clarity. ๐•๐ข๐ž๐ฐ ๐๐ƒ๐…
Modern Two Column A sleek design that utilizes two columns for better organization. ๐•๐ข๐ž๐ฐ ๐๐ƒ๐…

Internationalization

  • Multi-Language UI: Interface available in English, Spanish, Chinese, Japanese, and Portuguese (Brazilian)
  • Multi-Language Content: Generate resumes and cover letters in your preferred language

Roadmap

If you have any suggestions or feature requests, please feel free to open an issue on GitHub or discuss it on our Discord server.

  • AI Canvas for crafting impactful, metric-driven resume content
  • Email template generator for job applications
  • Multi-job description optimization

How to Install

For detailed setup instructions, see SETUP.md (English) or: Espaรฑol, ็ฎ€ไฝ“ไธญๆ–‡, ๆ—ฅๆœฌ่ชž.

Prerequisites

Tool Version Installation
Python 3.13+ python.org
Node.js 22+ nodejs.org
uv Latest astral.sh/uv

Quick Start

Fastest for MacOS, WSL and Ubuntu users:

bash
# Clone the repository
git clone https://github.com/srbhr/Resume-Matcher.git
cd Resume-Matcher

# Backend (Terminal 1)
cd apps/backend
cp .env.example .env        # Configure your AI provider
uv sync                      # Install dependencies
uv run app

# Frontend (Terminal 2)
cd apps/frontend
npm install
npm run dev

Open http://localhost:3000 and configure your AI provider in Settings.

Supported AI Providers

Provider Local/Cloud Notes
Ollama Local Free, runs on your machine
OpenAI Cloud GPT-5 Nano, GPT-4o
Anthropic Cloud Claude Haiku 4.5
Google Gemini Cloud Gemini 3 Flash
OpenRouter Cloud Access to multiple models
DeepSeek Cloud DeepSeek Chat

Docker Deployment

Official Docker images are published for linux/amd64 and linux/arm64 on:

  • ghcr.io/srbhr/resume-matcher
  • srbhr/resume-matcher

Run on a single public port (3000) with API available at /api:

bash
docker run --name resume-matcher \
  -p 3000:3000 \
  -v resume-data:/app/backend/data \
  ghcr.io/srbhr/resume-matcher:latest

Prefer pinning a version in production, for example ghcr.io/srbhr/resume-matcher:1.2.0 or
ghcr.io/srbhr/resume-matcher:1.2.

Endpoints:

Using Ollama with Docker? Use http://host.docker.internal:11434 as the Ollama URL instead of localhost.

Tech Stack

Component Technology
Backend FastAPI, Python 3.13+, LiteLLM
Frontend Next.js 16, React 19, TypeScript
Database TinyDB (JSON file storage)
Styling Tailwind CSS 4, Swiss International Style
PDF Headless Chromium via Playwright

Join Us and Contribute

We welcome contributions from everyone! Whether you're a developer, designer, or just someone who wants to help out. All the contributors are listed in the about page on our website and on the GitHub Readme here.

Check out the roadmap if you would like to work on the features that are planned for the future. If you have any suggestions or feature requests, please feel free to open an issue on GitHub and discuss it on our Discord server.

Contributors

Star History

Resume Matcher is a part of [Vercel Open Source Program](https://vercel.com/oss)

2. Official Technical Reference & Guides (srbhr/Resume-Matcher-docs)

The Resume Matcher takes your resume and job descriptions as input, parses them using Python, and mimics the functionalities of an ATS, providing you with insights and suggestions to make your resume ATS-friendly.

The process is as follows:

  1. Parsing: The system uses Python to parse both your resume and the provided job description, just like an ATS would. Parsing is critical as it transforms your documents into a format the system can readily analyze.

  2. Keyword Extraction: The tool uses advanced machine learning algorithms to extract the most relevant keywords from the job description. These keywords represent the skills, qualifications, and experiences the employer seeks.

  3. Key Terms Extraction: Beyond keyword extraction, the tool uses textacy to identify the main key terms or themes in the job description. This step helps in understanding the broader context of what the resume is about.

  4. Vector Similarity Using Qdrant: The tool uses Qdrant, a highly efficient vector similarity search tool, to measure how closely your resume matches the job description. This process is done by representing your resume and job description as vectors in a high-dimensional space and calculating their cosine similarity. The more similar they are, the higher the likelihood that your resume will pass the ATS screening.

On top of that, there are various data visualizations that I've added to help you get started.

Introduction

This guide is intended for anyone who wants to download and install Resume-Matcher
Follow these steps to setup the environment and run the application

QuickStart

  1. Fork the repository here.

  2. Clone the forked repository.

    bash
    git clone https://github.com/<YOUR-USERNAME>/Resume-Matcher.git
cd Resume-Matcher

  3. Create a Python Virtual Environment:

    • Using virtualenv:

      Note: Check how to install virtualenv on your system here link.

      bash
      virtualenv env

    OR

    • Create a Python Virtual Environment:

      bash
      python -m venv env

    OR

    • Create a Python Virtual Environment:

      bash
      py -<YOUR_VERSION_OF_PYTHON> -m pip install virtualenv

After you create your Virtual environment you should have a folder in your repo that looks something like myenv

  1. Activate the Virtual Environment.

    • On Windows.

      bash
      env\Scripts\activate

    • On macOS and Linux.

      bash
      source env/bin/activate

  2. Install Dependencies:

    bash
    pip install -r requirements.txt

  3. Prepare Data:

    • Resumes: Place your resumes in PDF format in the Data/Resumes folder. Remove any existing contents in this folder.
    • Job Descriptions: Place your job descriptions in PDF format in the Data/JobDescription folder. Remove any existing contents in this folder.
    • Initially the folders should look like belwo

  4. Parse Resumes to JSON:

    python
    python run_first.py

  5. Run the Application:

    python
    streamlit run streamlit_app.py

Note: For local versions, you do not need to run "streamlit_second.py" as it is specifically for deploying to Streamlit servers.

Additional Note: The Vector Similarity part is precomputed to optimize performance due to the resource-intensive nature of sentence encoders that require significant GPU and RAM resources. If you are interested in leveraging this feature in a Google Colab environment for free, refer to the upcoming blog (link to be provided) for further guidance.

Explore Related Technologies & Topics

View All 9,111+ Repositories โ†’

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#applicant-tracking-system Browse applicant-tracking-system catalog โ†’ #ats Browse ats catalog โ†’ #hacktoberfest Browse hacktoberfest catalog โ†’ #machine-learning Browse machine-learning catalog โ†’ #natural-language-processing Browse natural-language-processing catalog โ†’ #nextjs Browse nextjs catalog โ†’ โšก MCP Servers Model Context Protocol โ†’ ๐Ÿง  Agent Skills Prompt & rule files โ†’ ๐Ÿ”Œ OpenAPI Specs REST & Swagger schemas โ†’