Skip to content

Installation and Setup

Jump to bottom
Melancholy Sky edited this page Jun 10, 2026 · 4 revisions

Installation & Setup

System Requirements

Windows

Minimum Recommended
OS Windows 10 Windows 10 or 11 (64-bit)
Processor Any dual-core (2010+) Any modern CPU
Memory 4 GB RAM 8 GB RAM
Storage TF2 install + 500 MB free SSD recommended (faster VPK reads)
Python 3.8+ 3.11+
Additional TF2 installed via Steam TF2 installed via Steam

SteamOS + Linux

Minimum Recommended
OS Any modern 64-bit distro Ubuntu 20.04+, Arch, or equivalent
Processor Any dual-core (2010+) Any modern CPU
Memory 4 GB RAM 8 GB RAM
Storage TF2 install + 500 MB free SSD recommended (faster VPK reads)
Python 3.8+ 3.11+
Additional TF2 installed via Steam TF2 installed via Steam

MacOS 10.14 (Mojave) or later is also supported. Python 3.8+ required.

First run parses TF2's item schema — this may take a moment. Subsequent runs load from cache and start significantly faster.

Requirements

Requirement Details
Python 3.8 or later — python.org/downloads
TF2 Installed via Steam
vpk library Installed automatically on first run
vdf library Installed automatically on first run (optional but recommended)
Casual Preloader Recommended for using output files — download here

Downloading TF2autoswap

  1. Go to the releases page
  2. Download the latest release zip — TF2Autoswap_V4.7.zip
  3. Extract the zip to a folder of your choice

The extracted folder should contain:

TF2autoswap_v4.7/
  tf2autoswap.py
  tf2_core.py
  tf2_schema.py
  README.md
  CHANGELOG.md
  LICENSE
  TESTING.md

Keep all files in the same folder. Do not move them separately.

Running for the first time

Open a terminal in the folder and run:

python3 tf2autoswap.py

On the first run the tool will:

  1. Show the risk warning — read it and type agree to continue
  2. Detect your TF2 installation automatically
  3. Install the vpk library if not already present
  4. Install the vdf library if not already present
  5. Parse and cache item names from TF2's item database (first run only — subsequent runs load from cache)
  6. Open the main menu

On subsequent runs a one-line reminder replaces the full warning.

Platform notes

Platform Status Notes
Linux ✅ Fully tested Primary development platform
Windows ✅ Tested See note below
macOS ⚠️ Untested Should work — testers welcome

Windows note

On first run, Windows may show a warning about pip installing scripts to a location not on PATH. This is standard Windows behaviour and does not affect how the tool works. This warning has been suppressed as of v4.7.

MacOS note

TF2autoswap itself should work on macOS 10.14 or later. However, Casual Preloader compatibility with macOS is currently unknown. macOS users are recommended to follow the Linux instructions for the Casual Preloader as a starting point.

TF2 path detection

The tool automatically checks common Steam installation paths on all platforms.

If TF2 is not found automatically, you can set the path manually:

python3 tf2autoswap.py --tf2 "C:/path/to/steamapps/common/Team Fortress 2/tf"

Output folder

Built mods and tool data are saved inside the tool folder itself:

TF2autoswap_v4.7/
  output/                  ← built VPKs saved here
  output/tf2autoswap.log   ← errors and build history
  output/schema_cache.json ← item name cache (auto-generated)
  output/.acknowledged     ← risk warning acknowledgement flag

This keeps everything self-contained. To move or share the tool, zip the whole folder.

Clone this wiki locally