Installing getiplayer is quicker than you might expect for a command-line tool. On Windows and Mac there are official installers that bundle everything you need, and on Linux the setup is a short manual job. This guide walks you through each platform in turn, explains the one dependency that really matters, and finishes with a simple test so you know your install works before you try to record anything. By the end, you will have get_iplayer running in your terminal and ready for your first search.
What you need before you start
get_iplayer itself is a program written in Perl. On Windows and Mac, the official installers include Perl and the helper tools, so you do not have to hunt anything down yourself. On Linux, you will want Perl with its standard modules available, which most systems already have or can add through their package manager.
The other name to know is ffmpeg. get_iplayer downloads programme streams and then relies on ffmpeg to assemble them into finished MP4 and M4A files. If ffmpeg is missing, downloads appear to run and then fail at the final step, which confuses a lot of new users. The installers bundle or arrange what you need, but it is worth remembering the pairing: getiplayer finds and fetches, ffmpeg finishes the file.
- A computer running Windows, macOS, or Linux.
- An internet connection for the installer and your first cache refresh.
- A few minutes in a terminal or command prompt.
Installing on Windows
Windows has the simplest route. The get_iplayer project publishes an official installer through its GitHub releases page, and that installer bundles everything the tool needs, including Perl and the helper programs. Download the installer, run it, and follow the prompts like any other Windows setup.
When it finishes, open a command prompt and type get_iplayer followed by a programme name to test it, for example get_iplayer "Doctor Who". The first run takes a little longer than later ones because the tool builds its programme cache from the BBC feeds. Once results scroll past, your install is working.
Installing on a Mac
Mac users have two good options. The project offers an official installer package, which you download and run in the usual way. That is the safest choice if you just want getiplayer working with the least fuss.
If you already use Homebrew, the Mac package manager, you can install get_iplayer from there instead with a single command:
brew install get_iplayer
Homebrew handles the dependencies for you. Either way, open the Terminal app when you are done and run a test search. As on Windows, the first run builds the programme cache, so give it a moment before you judge the results.
Installing on Linux
Linux installs take a touch more manual work, but nothing exotic. Some distributions carry get_iplayer in their own package repositories, so check your distro’s packages first. If yours does not, or you want the latest release, the manual install from the project’s GitHub page is the standard route used by most Linux users.
Before or after installing, make sure two things are present on your system:
- Perl, with its standard modules, since get_iplayer is a Perl program.
- ffmpeg, since every finished recording passes through it.
Both are ordinary packages on every mainstream distribution. Once they are in place and get_iplayer is installed, open a terminal and run the same test search. If programme names appear, you are set.
Check that your install really works
A quick two-part check saves guesswork later. First, refresh the programme cache so you are searching current listings:
get_iplayer --refresh
Second, run a search for something the BBC definitely has on iPlayer right now, and look at the results. You should see programme names, each with an index number beside it. That number matters, because you can download a programme by typing its index number, and the beginner’s guide linked below shows you how.
If the search returns nothing at all, do not assume the install is broken. An empty result usually means a stale cache or a programme that has left iPlayer. The troubleshooting guide covers those cases, and most new users never need it once the cache is fresh.
Keeping getiplayer up to date
The BBC changes its feeds and stream systems from time to time, and get_iplayer updates to match. The tool itself helps you here: it prints a warning when your copy is out of date. When you see that warning, grab the newest release and install it over the old one.
Staying current is the single best habit for a trouble-free getiplayer setup. Many of the problems people report, broken feeds and failed downloads among them, disappear the moment they update to the latest 3.x release. Install the same way you did the first time; your settings and saved searches live in your profile folder, separate from the program.
A quick word on who can use it
One factual note before you start recording: BBC iPlayer is restricted to the UK, and UK viewers need a TV licence to use iPlayer. Recordings you make with get_iplayer are for your own personal use under the BBC’s terms. The installers work anywhere, but the BBC streams themselves follow those rules, and downloads attempted from outside the UK will fail because the streams are geo-restricted.
After installing: what the first run does
Your first get_iplayer run looks slower than the rest, and that is normal. Before it can answer a search, the tool builds its programme cache by reading the BBC feeds and indexing everything currently available. Depending on your connection, that first build can take a little while. Later runs reuse the cache and feel instant by comparison, refreshing it only when the data has gone stale or when you force an update with --refresh.
The install also creates your personal profile folder, called .get_iplayer, in your user account. That folder holds your cache, your settings, and any PVR searches you save later. It is worth knowing it exists, because it means your setup is portable: the program can be reinstalled or updated without disturbing the way you have configured it.
Reinstalling, updating, or moving machines
Sooner or later you will install getiplayer again: a new laptop, a fresh operating system, or an update after the tool warns you a newer release exists. The process is the same as the first install. Download the current installer or package for your platform and run it over the top of what is there. Your profile folder survives, so your options file and saved searches carry on working.
If you move to a new computer entirely, install getiplayer there and then copy your .get_iplayer folder across if you want your settings and PVR list to follow you. Your downloaded programmes are ordinary files, of course, so those move like any other media.
Conclusion
However you install getiplayer, the shape of the job is the same: run the official installer on Windows, the installer package or Homebrew on a Mac, or the package or manual route on Linux, and make sure ffmpeg is present. Run get_iplayer --refresh, try a search, and you have a working setup. Keep the tool updated when it tells you a new release exists, and you will rarely have to think about installation again. Next, it is time to record your first programme.
Read next:
Pingback: getiplayer Not Working? Common Errors and Fixes