# How to Manage Geoblocked IPTV Channels Across Countries Using Free-TV/IPTV

> Learn how to manage geoblocked IPTV channels using the Free-TV/IPTV repository. Discover how country codes and flags help bypass restrictions for seamless viewing.

- Repository: [Free TV/IPTV](https://github.com/Free-TV/IPTV)
- Tags: how-to-guide
- Published: 2026-06-26

---

**The Free-TV/IPTV repository handles geoblocked channels by marking them with the `Ⓖ` flag in country-specific markdown files and injecting ISO-3166-1 alpha-2 country codes into the `tvg-country` M3U attribute during playlist generation.**

Managing geoblocked IPTV channels across different countries requires a systematic approach to metadata and playlist generation. The Free-TV/IPTV project solves this through a transparent build process that converts markdown tables in `lists/*.md` into structured M3U playlists. By understanding how the [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) script processes country codes and the `Ⓖ` marker, you can effectively filter, add, or exclude region-locked streams.

## Understanding the Geo-Blocking Mechanism

The repository implements a two-layered approach to geoblocking: human-readable markers in source files and machine-parseable attributes in generated playlists.

### The Ⓖ Flag and Markdown Tables

Contributors indicate geo-restricted channels by appending the `Ⓖ` symbol to the channel name in the respective country markdown file. For example, in [`lists/usa.md`](https://github.com/Free-TV/IPTV/blob/main/lists/usa.md) line 7, a restricted channel appears as `BBC One Ⓖ`. This convention is documented in [`README.md`](https://github.com/Free-TV/IPTV/blob/main/README.md) lines 47-48, providing a visual cue for reviewers that the stream requires IP addresses from that specific country.

### Country Code Mapping in make_playlist.py

The `COUNTRY_CODES` dictionary in [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) (lines 45-46) maps file stems to ISO-3166-1 alpha-2 codes. When the script processes [`usa.md`](https://github.com/Free-TV/IPTV/blob/main/usa.md), it identifies the country as `US`; for [`uk.md`](https://github.com/Free-TV/IPTV/blob/main/uk.md), it assigns `GB`. This mapping ensures every channel carries accurate origin metadata regardless of the filename format.

### M3U Generation Logic

The `Channel.to_m3u_line()` method (lines 15-20) constructs the final `#EXTINF` entry. It conditionally adds `tvg-country="XX"` only when a country code exists, meaning geo-blocked streams are explicitly tagged while international channels omit the attribute. This stateless generation happens every time you run the build script, ensuring metadata stays synchronized with source changes.

## How Geo-Blocked Channels Are Processed

The workflow from source to playlist follows three distinct stages:

1. **Marking in Source Tables** – Contributors add the `Ⓖ` symbol to the Name column of the relevant markdown file (e.g., `France 2 Ⓖ` in [`lists/france.md`](https://github.com/Free-TV/IPTV/blob/main/lists/france.md)). They ensure the stream URL is active and marked with `[>]` rather than `[x]`.

2. **Country Identification** – [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) derives the country key from the filename ([`france.md`](https://github.com/Free-TV/IPTV/blob/main/france.md) → `france`) and performs a lookup in `COUNTRY_CODES` to retrieve the alpha-2 code (`FR`).

3. **M3U Output** – For each active line containing `[>]`, the script creates a `Channel` instance with the derived country code. The resulting entry includes `tvg-country="FR"`, which IPTV players can use for client-side filtering.

A typical geo-blocked entry appears as:

```m3u
#EXTINF:-1 tvg-name="BBC One" tvg-logo="https://…/BBC_One_logo.png" tvg-country="GB" group-title="UK",BBC One
https://vs-hls-pushb-uk-live.akamaized.net/x=4/i=urn:bbc:pips:service:bbc_one_yorks/iptv_hd_abr_v1.m3u8

```

## Managing Geoblocked Channels in Practice

### Exclude All Geo-Blocked Streams

Filter the generated playlist to remove lines containing country metadata. This produces a global-only playlist:

```bash
grep -v 'tvg-country' playlist.m3u8 > playlist_no_geo.m3u8

```

### Isolate Specific Countries

Use the `tvg-country` attribute to extract region-specific content. To create a UK-only playlist without geo-blocked streams (for use outside the UK):

```bash
grep 'tvg-country="GB"' playlist.m3u8 > uk_geo_only.m3u8

```

### Add New Geo-Blocked Channels

1. Edit the appropriate `lists/<country>.md` file.
2. Insert a new table row using the `[>]` marker, include the `Ⓖ` flag in the channel name, and verify the stream URL.
3. Submit a pull request. The [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) script will automatically attach the correct `tvg-country` attribute during the next build.

### Remove or Disable Channels

To remove a channel from the generated playlist, replace the `[>]` marker with `[x]` in the markdown source. Alternatively, delete the line entirely. The next run of [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) will omit the entry from `playlist.m3u8`.

## Automation Examples

Generate the full global playlist from source:

```bash
python3 make_playlist.py

```

Extract only geo-blocked entries for analysis:

```bash
grep -i 'tvg-country' playlist.m3u8 > geo_blocked.m3u8

```

Build a country-specific playlist excluding that country's geo-blocked content (useful for testing international availability):

```bash
python3 make_playlist.py
grep -v 'tvg-country="DE"' playlist.m3u8 > germany_international.m3u8

```

## Summary

- **The `Ⓖ` flag** in markdown tables provides human-readable indication of geo-restrictions, while the **`tvg-country`** attribute enables machine filtering.
- **Country codes** are derived from filenames via the `COUNTRY_CODES` mapping in [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) and injected at build time.
- **Active streams** are marked with `[>]` in source files; changing to `[x]` removes them from the output.
- **Playlist filtering** using standard Unix tools like `grep` allows you to include or exclude geo-blocked content without modifying source code.

## Frequently Asked Questions

### What does the Ⓖ symbol mean in Free-TV/IPTV channel lists?

The `Ⓖ` symbol indicates that a channel's stream URL is restricted to IP addresses from that specific country (geo-IP blocked) or requires a regional license to view. It appears in the Name column of the markdown tables within `lists/*.md` files and serves as a visual marker for contributors and users.

### How do I filter out all geoblocked channels from my playlist?

Run a negative grep filter against the `tvg-country` attribute: `grep -v 'tvg-country' playlist.m3u8 > clean_playlist.m3u8`. This removes all lines containing country codes, leaving only internationally available streams.

### Can I generate a playlist for only one specific country using Free-TV/IPTV?

Yes. First generate the full playlist with `python3 make_playlist.py`, then filter for your target country code: `grep 'tvg-country="FR"' playlist.m3u8 > france_only.m3u8`. The `tvg-country` attribute is standardized to ISO-3166-1 alpha-2 codes as defined in the `COUNTRY_CODES` mapping.

### Where is the country code metadata added in the M3U file?

The `tvg-country` attribute is added to the `#EXTINF` line by the `Channel.to_m3u_line()` method in [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) (lines 15-20). It appears immediately after the `tvg-logo` attribute and before `group-title`, populated from the `COUNTRY_CODES` dictionary lookup based on the source markdown filename.