CS-HLTV Downloader

Portable CS2 demo downloader and parser for HLTV professional matches. Designed to run from a USB drive on any Windows machine — zero install required.

Features

• Scrape and download CS2 demo files (.dem) from HLTV match pages
• Filter by event name, map pool, and date range
• Manifest-based resume — interrupted downloads pick up where they left off
• Optional pipeline mode: download + parse to parquet + delete .dem in one shot
• USB-portable: bundled Python + offline wheels, no internet needed for setup
• Bypasses Cloudflare protection via curl_cffi

Quick Start

On your own machine (prepare USB bundle)

pip install -r requirements.txt
python prepare_usb.py

This downloads an embeddable Python, pre-fetches wheels, and bundles 7-Zip. Copy the entire folder to a USB drive.

On any Windows machine

setup.bat            # one-time dependency install (choose mode 1 or 2)

Then either:

launch_run_download.bat     # download .dem files only
launch_run_pipeline.bat     # download -> parse to parquet -> delete .dem

Or run directly:

python run_download.py                        # download demos
python run_download.py --dry-run              # preview without downloading
python run_pipeline.py                        # download + parse + cleanup
python run_pipeline.py --config my_config.yaml

Configuration

Edit hltv_config.yaml:

target_demos: 1000        # how many map demos to collect
cutoff_days: 400          # ignore matches older than this

allowed_events:           # filter by tournament (empty = all)
  - "ESL Pro League Season 23"
  - "IEM Katowice 2025"
  # ...

maps:                     # which maps to keep
  - de_mirage
  - de_inferno
  - de_dust2
  - de_nuke
  - de_ancient
  - de_overpass
  - de_anubis

rate_limit:
  min_delay: 2            # seconds between requests
  max_delay: 5
  pause_every: 100        # pause after N downloads
  pause_duration: 30      # pause seconds

Project Structure

├── run_download.py          # download-only entry point
├── run_pipeline.py          # download + parse entry point
├── prepare_usb.py           # USB bundle builder (run on your machine)
├── setup.bat                # one-time setup on target machine
├── hltv_config.yaml         # configuration
├── requirements.txt         # download-only deps
├── requirements_pipeline.txt # full pipeline deps
├── launch_run_download.bat  # launcher (uses bundled Python)
├── launch_run_pipeline.bat  # launcher (uses bundled Python)
├── hltv/                    # HLTV scraping modules
│   ├── scraper.py           # HTTP client with rate limiting
│   ├── parser.py            # HTML parsing for results/match pages
│   ├── downloader.py        # archive download + extraction
│   └── manifest.py          # resume manifest (ndjson)
└── parsing/                 # demo parsing modules
    ├── demo_parser.py       # .dem -> parquet conversion
    ├── label_extractor.py   # bomb site label extraction
    └── map_utils.py         # coordinate normalization

Dependencies

Download-only mode:

• curl_cffi — HTTP with Cloudflare bypass
• beautifulsoup4 + lxml — HTML parsing
• pyyaml — config loading

Pipeline mode (adds):

• demoparser2 — Rust-backed CS2 demo parser
• pyarrow + pandas + numpy — parquet output

Requirements

• Python 3.10+
• 7-Zip (for .rar demo archives) — auto-downloaded by prepare_usb.py, or install system-wide

License

MIT