How to Use getiplayer: Beginner's Guide

Your first getiplayer download is the moment the tool stops feeling abstract. In the next few minutes you will refresh the programme listings, search BBC iPlayer for something you want, and record it to your computer as a file you can play anywhere. This beginner’s guide takes it one small step at a time, in the order you will actually do it, and explains what you are seeing on screen as you go. No experience with command lines is assumed. If you can type a sentence and press Enter, you can do everything in this guide.

Step 1: Refresh the programme cache

get_iplayer does its searching in a local cache, an index of everything currently on iPlayer and BBC Sounds. Search that cache and you find programmes in seconds, without the tool querying the BBC for every keystroke. The catch is that the cache ages. New programmes arrive and old ones expire, so an out-of-date cache gives out-of-date answers.

The fix takes one command:

get_iplayer --refresh

Run it, wait while the tool pulls the latest listings from the BBC feeds, and you are searching today’s catalogue. The tool refreshes the cache on its own when it decides the data is stale, but forcing a refresh before an important search is a good habit. Most “it found nothing” mysteries are just an old cache, and you have now removed that problem before it starts.

Step 2: Search for a programme

Now search. Type the programme name in quotes after the command, like this:

get_iplayer "The Repair Shop"

The tool matches your words against programme names in the cache and prints a list of results. Each result comes with an index number, which is simply the position of that programme in the results list. You will use that number in a moment.

A few tips make searching smoother. Use the exact name the BBC lists where you can, because the matching works on the titles in the catalogue. If your search finds too much, narrow it with --type=tv or --type=radio to look at only one kind of programme. Add --long to see longer descriptions in the results, which helps when a series has many similar episodes and you need to tell them apart.

Step 3: Look closer before you download

Before recording anything, you can inspect a programme properly with the --info option. It shows the full details for a programme without downloading it: what it is, when it was broadcast, and what you are about to fetch.

get_iplayer --info "The Repair Shop"

This step is optional, but new users find it reassuring. It confirms you have the right episode, and it teaches you how the BBC describes programmes in its feeds. Once you trust the search results, you will skip it most of the time and go straight to downloading.

Step 4: Download with –get

Here is the main event. Add --get to your search and get_iplayer records the programmes that match:

get_iplayer --get "The Repair Shop"

The tool fetches the stream and passes it to ffmpeg, which builds the finished file. Television becomes an MP4 video, and radio becomes an M4A audio file. Progress scrolls in the terminal while it works, and when the prompt returns, your file is done.

One warning: a broad search with --get downloads every match. Search for a whole series name and you may queue up a pile of episodes. That is sometimes exactly what you want, and the PVR feature exists for doing it repeatedly, but for your first download, pick something specific so you can watch the process end to end.

Two other ways to choose what downloads

Searching by name is the friendly route, but getiplayer gives you two more precise options.

By index number. After a search, you can download a result by its number instead of repeating the name. It is handy when several episodes share a title and you only want one of them.
By PID. Every BBC programme has a programme ID, the code at the end of its iPlayer or Sounds web page address. Copy that code and download the exact programme with get_iplayer --pid followed by the code. There is no ambiguity with a PID; you get precisely that broadcast.

Most people live happily on name searches and index numbers, and reach for a PID when a friend sends them a link to a specific episode.

Step 5: Find and play your file

When the download completes, the file sits in the tool’s output folder on your computer, named after the programme and episode. Television files are MP4, which plays in practically every media player, browser, and TV app you own. Radio files are M4A audio, equally at home in music players and podcast apps.

If you would like your downloads in a specific folder instead of the default, the --output setting handles that, and you can save it permanently in the options file so you never type it again. The options file guide linked below explains how, along with custom file naming.

If your search finds too much, or too little

Two search problems greet almost every beginner, and both have easy answers. If a search finds too much, usually because the programme name is a common word or a long-running series has hundreds of episodes, narrow it down. Add --type=tv or --type=radio, filter by --channel, and use the index numbers to pick exactly one result instead of downloading by name.

If a search finds too little, or nothing at all, refresh the cache and try again with the exact title the BBC uses. Programmes also leave iPlayer when their window closes, so a show you saw last month may honestly be gone. A quick check on the iPlayer website tells you which of those two situations you are in.

Try a radio download as your second

Once your first TV download works, repeat the trick with radio. The commands are identical apart from --type=radio, and the result is a small M4A audio file instead of a video. Radio downloads finish fast, which makes them a friendly way to practise: search a favourite BBC Sounds show, record one episode, and play it in your music app. You have then used getiplayer for both halves of the BBC catalogue, and everything in the other guides on this site builds on those same moves.

Three habits that save frustration

Refresh first. A stale cache is behind most failed searches, so --refresh before a session costs nothing.
Mind the window. Programmes stay on iPlayer for a limited time, often around 30 days, and then they are gone. If you want something, record it while it is available.
Stay current. When getiplayer warns you that a newer release exists, update. BBC-side changes are the other big cause of sudden failures.

And the plain factual bit: iPlayer is a UK service, UK viewers need a TV licence to use it, and your recordings are for personal use under the BBC’s terms.

Conclusion

Your first getiplayer download really is just five moves: refresh the cache, search by name, glance at the results, add --get, and collect your MP4 or M4A file. Everything else the tool does, quality settings, subtitles, automatic series recording, builds on those same commands. Run through this guide once with a programme you like, and the getiplayer basics are yours. The cheat sheet below is the natural next read when you want the wider set of commands.

Read next:

How to Use get_iplayer: Beginner’s Guide to Your First Download