How to use Custom Maps and setup FastDL for Team Fortress 2

This guide covers the map cycle, hosting Steam Workshop maps, adding custom maps by hand, and setting up a fast download (sv_downloadurl) so players are not stuck on the Source engine's painfully slow built-in download. Complete Getting started with your Team Fortress 2 server first.

The Map Cycle

tf/cfg/mapcycle.txt lists the maps the server rotates through, one per line:

ctf_2fort
cp_dustbowl
pl_badwater
koth_viaduct
cp_gravelpit
pl_upward
cp_steel

The server advances to the next map when the time limit (mp_timelimit) or round limit is reached.

Steam Workshop maps go in this file too, under their Workshop map name rather than a plain map name — see the next section.

To force a specific map on boot, set +map cp_dustbowl in the Startup tab arguments (or use the Startup map field).

For player-controlled rotation (voting, nominations, RTV), install MapChooser Extended, covered in SourceMod Plugins. With it, players vote on the next map near the end of each round.

Steam Workshop Maps

A TF2 server can host a Workshop map without anyone downloading a .bsp. Valve wired Workshop map names into the map commands and into the mapcycle, and the server fetches the file itself. This is not a legacy feature that quietly rotted — Valve was still shipping fixes to Workshop map loading in an October 2025 update.

Workshop Map Names

Anywhere TF2 takes a map name, it also takes a Workshop map name. Valve's release note is explicit:

Workshop map names (e.g. workshop/cp_foo.ugc123456) can now be used in the map, changelevel, and nextlevel commands as well as the mapcycle config

There is a shorthand, so you do not need to know the map's file name — the numeric Workshop ID on its own resolves:

Shorthand workshop map names of the form workshop/<id> (e.g. workshop/123456) will now auto-resolve to the full map name

That ID is the number after ?id= on the map's Workshop page:

https://steamcommunity.com/sharedfiles/filedetails/?id=123456
                                                      ^^^^^^

Using Them

changelevel workshop/123456
nextlevel workshop/cp_foo.ugc123456

+map workshop/123456

ctf_2fort
pl_upward
workshop/123456
workshop/cp_foo.ugc123456

Valve added fuzzy name matching to the same four places in the same update — changelevel dustbowl resolves to the full map name — which is worth knowing once Workshop names start getting long.

Downloads Happen on Demand

Nothing has to be synced up front:

Running tf_workshop_map_sync is no longer necessary, maps will be fetched and updated on demand during level change

A Workshop entry in mapcycle.txt therefore downloads itself the first time the rotation reaches it, and it is updated the same way when the author republishes. That second half is the real advantage over uploading a .bsp by hand: a hand-uploaded map stays at whatever version you uploaded, however many times the mapper fixes it.

The cost is a pause on that first level change while the file comes down. Precache ahead of time to avoid it:

tf_workshop_map_sync is no longer blocking, and can be used to precache maps in the background

Workshop Maps Do Not Need FastDL

Players pull Workshop content from Steam rather than from your game server or your FastDL host. Valve, announcing the Maps Workshop, put it as plainly as it can be put: you can "just connect to a server running a Workshop map and it will download automatically from the Workshop."

That is the practical reason to prefer the Workshop for any map that is on it — it sidesteps the 64kb/s problem the FastDL section below exists to solve. FastDL is still what you need for maps that are not on the Workshop, and for loose custom materials and sounds.

Workshop maps are not in tf/maps/

"Workshop maps are no longer copied to tf/maps/workshop/ by default, instead using the single copy in the steamapps/workshop folder." Do not go looking for the .bsp under tf/maps/ and conclude the download failed — it was never going to be there.

Adding Custom Maps

Maps that are not on the Steam Workshop have to be uploaded by hand. This is also the route for a map you want pinned to one exact version.

1. Find a map on gamebanana.com/maps or another source.

2. Download the .bsp file.

3. Upload it to tf/maps/ via SFTP or the File Manager on your hosted Team Fortress 2 server.

4. Add the map name (without the .bsp extension) to mapcycle.txt.

5. Restart, or switch to it live with changelevel mapname.

Some maps come with extra files (custom textures, sounds, particles). Upload those to the matching tf/ subfolders (tf/materials/, tf/sound/, etc.) so the map renders correctly.

Playing a Custom Map on Your Own Client

A map you download from GameBanana is a .bsp, and on your own machine it goes in the same place it goes on the server:

steamapps/common/Team Fortress 2/tf/maps/

That is the folder the game loads maps from. A .bsp sitting there is playable immediately — no mapcycle.txt entry, no restart.

Maps you picked up by joining a server are a different case. They arrive on their own — as Valve's wiki puts it, "upon joining a server currently playing a custom map, the map files start downloading automatically if the player does not already have it" — but they land in tf/download/maps/, the engine's separate path for server-supplied content, not in tf/maps/. That is fine while you are connected and no help offline. If map cp_custom tells you the map is not found, copy the .bsp from tf/download/maps/ into tf/maps/.

Players can turn custom downloads off

The same wiki notes it "is possible to disable custom content downloads in the options menu; however, doing so prevents downloading custom maps from servers". If one player reports timing out on every custom-map server while everyone else connects, check that setting before you touch FastDL.

Enabling the developer console

You need the console to type map at all. Turn it on in Options → Keyboard → Advanced → Enable Developer Console, then open it with the backtick/tilde key (the one to the left of 1). Adding -console to the game's launch options does the same job, and -developer opens the console automatically on startup.

map offline versus changelevel on the server

They are not interchangeable.

• map cp_custom changes the map and restarts the server. Run from the main menu it starts a new local server, which is how you load a custom map on your own machine without going through the Create Server dialog.
• changelevel cp_custom changes the map on a server that is already running, without the restart. This is the one to use in your panel Console on a live server — map restarts and drops everyone.

Neither adds the map to rotation. That still needs the name in mapcycle.txt, as above.

Fast Downloads (sv_downloadurl)

The one thing to get right on a custom-map server

This is the single most important thing for any server running custom maps.

The Problem

Without sv_downloadurl, players download custom content over Source networking, which is capped at 64 kb/s — about 8 KB/s — one file at a time. A 60 MB custom map is well over an hour at that rate, and players give up and disconnect long before it finishes.

The Fix

Host your custom files on a normal HTTP web server and point the game at it:

1. Host the contents of tf/maps/ (and any custom tf/materials/, tf/sound/) on a web server, your own or a CDN.

2. In server.cfg, set:

   sv_downloadurl "https://fastdl.yourdomain.com/tf/"
   sv_allowdownload 1
   sv_allowupload 1
   

3. Mirror the server's folder structure on the HTTP host. A map at tf/maps/cp_custom.bsp on the game server must be reachable at https://fastdl.yourdomain.com/tf/maps/cp_custom.bsp.

Now custom downloads come from your fast HTTP server at full speed instead of the throttled game server.

Compressing Files (Optional but Recommended)

Source supports bzip2-compressed fast-download files. Compress each .bsp to .bsp.bz2 and host both. Clients download the smaller compressed version and decompress locally, cutting download time further. Tools like bzip2 on the command line produce these.

Hosting Options

• Your own web server: Full control, mirror the tf/ structure
• A dedicated FastDL host: Some providers offer FastDL space specifically for this
• A CDN or object storage (S3-compatible, etc.): Works as long as the path structure matches and files are publicly readable

sv_pure and Custom Content

sv_pure controls how strictly the server enforces client file consistency:

Pick the value that matches your server's purpose

For trade and casual servers running lots of custom content, sv_pure 0 is typical. For competitive integrity, sv_pure 1 or higher.

Common Issues

• Custom maps not downloading for clients: sv_downloadurl not set, or sv_allowdownload 0. Confirm both. Also confirm the file is actually reachable at the mirrored URL path (paste it in a browser).
• Map downloads but textures are missing: The map's custom materials/sounds were not uploaded, or not mirrored to the FastDL host. Upload the full content set.
• FastDL URL returns 404: Folder structure mismatch. The path after the base URL must exactly mirror the tf/ structure (e.g., /tf/maps/yourmap.bsp).
• Map not in rotation: Confirm it is listed in mapcycle.txt with the correct name (no .bsp extension) and that the .bsp is in tf/maps/.
• A Workshop map never loads: The first fetch happens during the level change, and a large map takes a while — read the console output before restarting. If it still fails, check the number is the Workshop ID taken from the map's own Workshop page.
• tf/maps/ looks empty after a Workshop map loads: Expected. Workshop maps are used from the single copy in steamapps/workshop, not copied into tf/maps/.

What to Read Next

• SourceMod Plugins for MapChooser Extended (map voting and RTV)
• Game Mode Servers for maps tied to specific game modes
• Getting started with your Team Fortress 2 server for the server.cfg settings referenced here
• Team Fortress 2 Admin Commands to change maps and run map votes from the console
• TF2 Bot Commands if you want bots on a custom map, which needs a navigation mesh

Made with 💜 by GameServerKings