Skip to content

Usage Guide

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

Usage Guide

TF2autoswap has two modes — interactive and command line.

Interactive mode

Run with no arguments to open the main menu:

python3 tf2autoswap.py

The menu has four options:

Option What it does
  1. Create a cosmetic swap | Guided 5-step flow for swapping cosmetic items
  2. Create a weapon swap | Guided 5-step flow for swapping weapon models
  3. List / remove mods I've made | Browse and delete built mods
  4. List addons in the preloader folder | See what is installed in the preloader

Searching for items

The tool searches TF2's internal file names (keywords) for items.

Search is flexible:

  • Spaces and underscores both work — searching hot air finds hot_air
  • Punctuation is ignored — crusader's getup finds crusaders_getup
  • If a keyword returns no results, the tool searches item names automatically
  • If there is only one match, it is selected automatically
  • Typos get a "did you mean" suggestion

Finding keywords manually

If you need to find a keyword yourself, use backpack.tf:

  1. Go to https://backpack.tf/overview/Item Name
  2. Find the line that says Player model defined as — the keyword is the file name shown there

Risk warning

On first run the tool shows a risk warning covering VAC bans, competitive league policies, and using the tool while TF2 is closed. Type agree to accept and continue. On subsequent runs a one-line reminder is shown instead.

To reset the acknowledgement (for testing or a fresh install), delete output/.acknowledged from the tool folder.

Dry run

Use --dry-run to preview a swap without writing any files:

python3 tf2autoswap.py scattergun pistol --weapon --dry-run

This shows the files that would be built and their sizes, then exits without saving anything. Also available as a preview in interactive mode at the confirm step.

Clone this wiki locally