Skip to content

Installation and Setup

Jump to bottom
Melancholy Sky edited this page Jun 8, 2026 · 5 revisions

Installation & Setup

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

Windows note

On first run, Windows may show a warning about pip installing scripts to a location not on PATH. This is a standard Windows behaviour and does not affect how the tool works. The warning is safe to ignore.

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 the log file are saved inside the tool folder itself:

TF2autoswap_v4.6/
  output/        ← built VPKs saved here
  tf2autoswap.log ← errors and build history

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

# Installation & Setup

Requirements

Requirement Details
Python 3.8 or later — [python.org/downloads](https://www.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](https://cueki.github.io/casual-pre-loader/)

Downloading TF2autoswap

  1. Go to the [releases page](https://github.com/TF2Autoswap/releases/releases)
  2. Download the latest release zip — TF2autoswap_v4.6.zip
  3. Extract the zip to a folder of your choice

The extracted folder should contain:

TF2autoswap_v4.6/
  tf2autoswap.py
  tf2_core.py
  tf2_schema.py
  README.md
  CHANGELOG.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. Detect your TF2 installation automatically
  2. Install the vpk library if not already present
  3. Install the vdf library if not already present
  4. Load item names from TF2's item database
  5. Open the main menu

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 a standard Windows behaviour and does not affect how the tool works. The warning is safe to ignore.

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 the log file are saved inside the tool folder itself:

TF2autoswap_v4.6/
  output/        ← built VPKs saved here
  tf2autoswap.log ← errors and build history

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

Clone this wiki locally