How to Add Custom Maps to a Team Fortress 2 Server

To add custom maps to a Team Fortress 2 server, upload the .bsp files to tf/maps/ and add each map's name, without .bsp, on its own line in tf/cfg/mapcycle.txt. Workshop maps skip the upload: add workshop/<ID> to the cycle and the server downloads them. For players, set sv_downloadurl in tf/cfg/server.cfg to a web host holding compressed copies in maps/<name>.bsp.bz2 (FastDL). Never replace a map with a new version under the same file name.

What you are working with

Players keep maps they downloaded in tf/download/maps/ in their own game folder, which is why a changed map with the same name causes trouble later.

Workshop or loose .bsp?

Method 1: Workshop maps (easiest)

Step 1: Get the ID

Open the map on the TF2 Workshop and copy the number at the end of the URL, after ?id=.

Step 2: Load it

Try it live from the server console:

changelevel workshop/454118349

The server downloads the map and loads it. To start on it, set the Default Map in our panel to workshop/454118349.

Step 3: Add it to the cycle

Add the same line to tf/cfg/mapcycle.txt. Maps in the map cycle are tracked by the server and kept up to date when their authors publish changes. tf_workshop_map_sync <ID> in the console does the same for a map you want tracked without putting it in the cycle.

Method 2: Loose .bsp maps

Step 1: Upload the map

Upload the .bsp to tf/maps/ with SFTP or the file manager. On Linux servers file names are case sensitive, so keep them exactly as the author named them, ideally all lowercase.

Step 2: Add it to mapcycle.txt

ctf_2fort
pl_upward
koth_product_final
cp_orange_x3
pl_mymap_rc2

One map per line, no .bsp. If tf/cfg/mapcycle.txt does not exist, create it. Copying mapcycle_default.txt from the same folder gives you the stock list to edit.

Step 3: Load it

Run changelevel pl_mymap_rc2 in the console, or wait for the rotation to reach it. server.cfg runs on each map change, so new settings apply then.

Step 4: Set up FastDL for players

Without FastDL, players download maps from the game server itself. That is slow, and Source caps it with net_maxfilesize: the default is 16 MB, and the highest you can set is 64 MB. Plenty of custom maps are bigger than 16 MB.

FastDL moves the downloads to a normal web host:

1. Compress each map with bzip2 so you get pl_mymap_rc2.bsp.bz2.
2. Upload them to a web host in a maps folder, for example https://dl.example.com/tf/maps/pl_mymap_rc2.bsp.bz2.
3. In tf/cfg/server.cfg, add:

sv_allowdownload 1
sv_downloadurl "https://dl.example.com/tf/"

The URL points at the folder that contains maps, not at maps itself. Keep the uncompressed .bsp on the game server too: the server needs it to run the map. Restart, and players pull the compressed file at web speed.

The gotcha: never overwrite a map with a new version

Every Source client compares its copy of a map with the server's. If a player downloaded pl_mymap.bsp last month and you replace it on the server with an updated file of the same name, that player gets "Your map differs from the server's" and cannot join until they delete their old copy from tf/download/maps/.

That is why mappers name versions _b4, _rc2 or _final2. When a map updates, upload it as a new file with the new name, swap the line in mapcycle.txt, and remove the old one. Workshop maps handle this themselves, which is a good reason to prefer them.

Common problems

• "Map not found" on changelevel: the name has a typo, includes .bsp, or the case differs from the file on a Linux server.
• Players get "Your map differs from the server's": the map was replaced under the same name. Rename the new version or have players delete theirs from tf/download/maps/.
• Players stuck or kicked while downloading: the map is bigger than net_maxfilesize. Set up FastDL.
• FastDL not used: the URL is wrong, files are not in maps/, or the .bz2 name does not match the .bsp name exactly. Open the full file URL in a browser to test.
• Rotation ignores your new maps: the file is not tf/cfg/mapcycle.txt, or the server did not change map since you edited it.

Custom maps on GamezServers

On a Team Fortress 2 server from GamezServers, the starting map is the Default Map setting, and maps go into tf/maps over the SFTP login in Settings or through the file manager, which also extracts zips and can download a map from a link straight to the server. Click Backup before a big rotation change, and the server keeps its regulars playing without anyone's PC on. Plugins next? See how to host a Team Fortress 2 server.

FAQ

Where do custom maps go on a TF2 server?

In tf/maps/ as .bsp files. Workshop maps download themselves when you use workshop/<ID>.

How do I add a Workshop map to the TF2 map cycle?

Add a line workshop/<ID> to tf/cfg/mapcycle.txt, using the number from the map's Workshop URL.

Do I need FastDL for a TF2 server?

Not for small maps, but most custom maps download far faster with it, and anything over the net_maxfilesize limit needs it.

Why do players get "Your map differs from the server's"?

They have an older copy of a map with the same file name. Upload new versions under a new name, or have players delete their copy in tf/download/maps/.