YouTube Channel Lookup Tool

A cross-platform command-line tool for bidirectional lookups between YouTube usernames (handles) and channel IDs using web scraping.

Features

• ✅ Username to Channel ID: Convert @username to channel ID
• ✅ Channel ID to Username: Convert channel ID to @username
• ✅ Cross-platform: Works on Windows, macOS, and Linux
• ✅ Configurable User Agent: Browser-like default with optional override
• ✅ Configurable Retries: Optional retry count and delay
• ✅ Multiple Output Modes: Default (bare value), URL, feed URL, or verbose

Installation

1. Clone or download this repository
2. Install the package (this also installs all dependencies and registers the youtube-lookup command):

pip install -e .

Or install dependencies only (use python youtube_lookup.py directly):

pip install -r requirements.txt

Note: After installing with pip install -e ., ensure your Python Scripts directory is on your PATH. Python will warn you if it isn't.

Usage

Output Modes

The tool supports four output modes. Only one can be active at a time:

Mode	Flag	Output
Default	(none)	Bare result — channel ID or @username
URL	--url	Channel URL
Feed	--feed	RSS feed URL
Verbose	--verbose / -v	All details: labels, channel URL, feed URL

Examples

Username → Channel ID (default):

youtube-lookup --username "MicrosoftCloud"
# UCSgzRJMqIiCNtoM6Q7Q9Lqw

Channel ID → Username (default):

youtube-lookup --channel-id "UCSgzRJMqIiCNtoM6Q7Q9Lqw"
# @MicrosoftCloud

Output just the channel URL:

youtube-lookup --username "MicrosoftCloud" --url
# https://www.youtube.com/channel/UCSgzRJMqIiCNtoM6Q7Q9Lqw

youtube-lookup --channel-id "UCSgzRJMqIiCNtoM6Q7Q9Lqw" --url
# https://www.youtube.com/@MicrosoftCloud

Output just the RSS feed URL:

youtube-lookup --username "MicrosoftCloud" --feed
# https://www.youtube.com/feeds/videos.xml?channel_id=UCSgzRJMqIiCNtoM6Q7Q9Lqw

Verbose output:

youtube-lookup --username "MicrosoftCloud" --verbose

Looking up channel ID for username: @MicrosoftCloud
Channel ID:  UCSgzRJMqIiCNtoM6Q7Q9Lqw
Channel URL: https://www.youtube.com/channel/UCSgzRJMqIiCNtoM6Q7Q9Lqw
Feed URL:    https://www.youtube.com/feeds/videos.xml?channel_id=UCSgzRJMqIiCNtoM6Q7Q9Lqw

With retries and delay:

youtube-lookup --username "MicrosoftCloud" --retry 5 --delay 2.0

Custom user agent:

youtube-lookup --username "MicrosoftCloud" --user-agent "MyBot/1.0"

All Options

usage: youtube-lookup [-h] (--username USERNAME | --channel-id CHANNEL_ID)
                      [--retry RETRY] [--delay DELAY]
                      [--verbose] [--url] [--feed]
                      [--user-agent USER_AGENT]

options:
  -h, --help                    show this help message and exit
  --username USERNAME, -u       YouTube username to lookup (with or without @)
  --channel-id CHANNEL_ID, -c   YouTube channel ID to lookup
  --retry RETRY, -r             Number of retry attempts (optional)
  --delay DELAY, -d             Delay between retries in seconds (optional)
  --verbose, -v                 Show full details: labels, channel URL, and feed URL
  --url                         Output just the channel URL
  --feed                        Output just the RSS feed URL
  --user-agent USER_AGENT, -A   User-Agent string to use (default: Chrome browser)

Technical Details

How It Works

1. Username to Channel ID:

   • Fetches youtube.com/@username
   • Extracts the channel ID from page metadata using regex patterns
   • Validates the channel ID format (UC prefix, 24 characters)

2. Channel ID to Username:

   • Fetches youtube.com/channel/<CHANNEL_ID>
   • Extracts the handle from canonicalBaseUrl in page metadata
   • Returns the canonical @username format

RSS Feed URL Format

https://www.youtube.com/feeds/videos.xml?channel_id=<CHANNEL_ID>

Default User Agent

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36

Override with --user-agent / -A.

Dependencies

• Python 3.6+
• requests

Error Codes

• 0: Success
• 1: Lookup failed (not found or network error after all retries)

Limitations

• Relies on web scraping — may break if YouTube changes their page structure
• Requires an internet connection
• May be subject to YouTube's terms of service
• Some channels may not have public usernames or may not be discoverable

Contributing

Feel free to submit issues and pull requests to improve the tool!

License

Copyright (c) 2026 Matthew Housholder. Released under the MIT License.