getiplayer Commands Cheat Sheet: Search and Download

Nobody wants to dig through documentation every time they record a programme. This getiplayer commands cheat sheet gathers the get_iplayer options you will actually use into one page, grouped by job, with plain examples you can copy and adapt. Keep it open while you work through your first few downloads, and soon you will type most of these from memory. Each command here works the same way in a Windows command prompt, a Mac terminal, and a Linux shell.

Searching for programmes

Every getiplayer session starts with a search. The tool matches your text against the programme names in its local cache and lists what it finds, each with an index number.

get_iplayer "Programme Name" runs a basic search across TV and radio.
get_iplayer --type=tv "Programme Name" limits results to television. Swap in --type=radio for BBC Sounds shows, or use the livetv and liveradio types.
get_iplayer --channel "BBC One" "Programme Name" filters by channel, which is a lifesaver when a name appears across several stations.
get_iplayer --category "Comedy" "Programme Name" filters by category instead.
get_iplayer --long "Programme Name" shows longer descriptions, so you can tell episodes apart at a glance.
get_iplayer --info "Programme Name" shows the full details for a programme without downloading anything.

Search results are only as fresh as your cache. If a search looks wrong or empty, refresh before you blame the programme name, which brings us to the maintenance command further down this page.

Downloading programmes

Downloading is a search plus one option. That small pattern covers most of what get_iplayer does.

get_iplayer --get "Programme Name" records every programme matching your search. Television saves as MP4, radio as M4A.
get_iplayer --get 123 downloads by index number, using the number shown beside a result in your search. This is the precise way to grab one episode from a long list.
get_iplayer --pid b0abc123 downloads one exact programme by its PID, the code at the end of its iPlayer or Sounds page address. Use the real code from the page you are looking at.
get_iplayer --get --pid b0abc123 is not needed; --pid on its own fetches that programme directly.

A safety note worth learning on day one: --get with a broad name downloads all the matches. A series name can mean thirty episodes. Search first without --get, read the results, and only then decide what to record.

Options that shape your downloads

These options change where files go, how good they look, and what comes with them.

--output /path/to/folder sends downloads to a folder you choose instead of the default.
--modes hvfhd asks for a particular quality level for TV. Modes are covered in depth in the quality guide linked below.
--subs includes subtitles with a TV download, saved as an SRT file alongside the video where the BBC provides them.
--subsonly downloads just the subtitles and skips the programme itself.
--thumb embeds the programme thumbnail and metadata into the finished file.
--aactomp3 converts radio downloads to MP3 instead of the default M4A.
--file-prefix "<name>-<episode>" controls how output files are named, using tokens such as <name>, <episode>, <pid>, and <mode>.

You can combine several in one command. A typical polished download looks like this: get_iplayer --get --subs --thumb --output /media/tv "Programme Name". Long commands like that are exactly what the options file exists for, so you can save the parts you always use and stop retyping them.

Recording whole series with the PVR

The PVR turns a search you like into a standing instruction. Instead of running the same search yourself every week, you save it once and let getiplayer repeat it.

get_iplayer --pvr-add "MySearch" --type=tv "Programme Name" saves a search under the name you give it. The search can carry any of your usual filters and options.
get_iplayer --pvr runs every saved search and downloads anything new that matches.

People often run --pvr on a schedule, with cron on Linux and Mac or Task Scheduler on Windows, so new episodes land on their drive without any attention at all. The PVR guide linked below sets this up step by step.

Cache and housekeeping

One command keeps your searches honest:

get_iplayer --refresh forces the programme cache to update from the BBC feeds right now, rather than waiting for the tool to decide it is stale.

Reach for it whenever a programme you can see on the iPlayer website refuses to appear in your results. Programmes only stay in the listings for a limited window, often around 30 days, so the cache reflects a moving target. A refresh lines your local index back up with reality.

Settings, presets, and the options file

Any option you type again and again can live in the options file instead, stored in your .get_iplayer profile folder. Settings there apply to every run, so your output folder, your preferred type, and your file naming are always in force. You can also keep named presets and load one with --preset, which suits people who download in two distinct ways, perhaps radio for the car and HD television for home, and want each setup saved under its own name.

Reading the screen while a download runs

New users sometimes stare at a busy terminal and wonder if everything is fine. A healthy getiplayer download has a recognisable rhythm. First the tool confirms what it is recording, showing the programme name and the mode it has chosen. Then you see download progress as the stream arrives. At the end, ffmpeg takes over briefly to assemble the finished file, and the tool reports where the MP4 or M4A has been saved, before returning you to the prompt.

That rhythm gives you a built-in diagnostic. If a run fails early, during the search or fetch stage, think about caches, names, and expiry. If it fails right at the end, after the stream arrived, think about ffmpeg and the conversion step. Noticing which stage broke turns a wall of text into a useful clue, and the fixes guide relies on exactly that distinction.

Five complete examples to copy

Search tonight’s drama: get_iplayer --type=tv --long "Programme Name"
Record one episode by its search number: get_iplayer --get 42
Record a radio show as MP3: get_iplayer --get --type=radio --aactomp3 "Programme Name"
Record a film with subtitles and artwork: get_iplayer --get --subs --thumb "Film Name"
Save a series to the PVR: get_iplayer --pvr-add "MySeries" --type=tv "Series Name"

Swap the names, numbers, and folders for your own, and each of those lines works as written.

One last habit ties the cheat sheet together: when a command works and you know you will use it again, save it. That might mean a line in the options file, a preset, or a PVR entry. The commands themselves are the easy part; a small library of your own proven commands is what makes getiplayer feel effortless.

Conclusion

The getiplayer command set looks wide, but it rests on a small core: search by name, narrow with --type, --channel, and --category, inspect with --long and --info, then record with --get, an index number, or a --pid. Around that core sit the quality-of-life options, --subs, --thumb, --modes, and --output, plus the PVR for hands-free series recording. Learn the core and the rest is just seasoning. When a command ever misbehaves, the fixes guide below is your next stop.

Read next:

get_iplayer Commands Cheat Sheet: Search, Download and More