Ultimate Guitar Scraper

Python library to download your favorited tabs from Ultimate-Guitar.com.

What Works

• Favorites: Download all your liked tabs (requires cookies)
• Tab Content: Get individual tab content by URL

What Doesn't Work Yet

Search is broken. Cloudflare blocks automated searches pretty consistently. If you want to help fix this, PRs are welcome. For now, use the UG website to find tabs, favorite them, then use this to download.

Installation

From PyPI (recommended)

pip install ultimate-guitar-scraper

For Cloudflare bypass support:

pip install ultimate-guitar-scraper[cloudflare]

From source

git clone https://github.com/yourusername/ug_api.git
cd ug_api
pip install -e .

Usage

Get your cookies from browser DevTools (F12 → Application → Cookies → ultimate-guitar.com). You need SESSIONUG and bbsessionhash.

from ug_api import UGScraper

cookies = {
    'SESSIONUG': 'your_session_cookie_here',
    'bbsessionhash': 'your_bb_session_here'
}

scraper = UGScraper(cookies)

# Get your favorites
result = scraper.get_favorites()
for tab in result['favorites']:
    print(f"{tab['artist']} - {tab['title']} ({tab['type']})")
    print(f"  URL: {tab['url']}")

# Download a specific tab
tab = scraper.get_tab("https://tabs.ultimate-guitar.com/tab/...")
if not tab['error']:
    print(tab['content'])

How to Get Cookies

1. Open Ultimate-Guitar.com in your browser
2. Log in
3. Press F12 to open DevTools
4. Go to Application tab → Cookies → ultimate-guitar.com
5. Copy the values for SESSIONUG and bbsessionhash
6. Paste them into the cookies dict

API

UGScraper(cookies)

Initialize with your UG session cookies.

Args:

• cookies (dict): Your UG cookies including SESSIONUG and bbsessionhash

get_favorites()

Get all your favorited tabs.

Returns:

{
    'favorites': [
        {
            'title': 'Song Name',
            'artist': 'Artist Name',
            'type': 'Chords',
            'url': 'https://...',
            'liked_at': '2024-01-01'
        }
    ],
    'error': None
}

get_tab(url)

Download tab content from a URL.

Returns:

{
    'title': 'Song Name',
    'artist': 'Artist Name',
    'content': '...',
    'url': 'https://...',
    'error': None
}

Known Issues

• No search: Cloudflare blocks search requests. Favorite tabs manually on the website first.
• Official tabs: Can't download official/licensed tabs
• Rate limiting: Use cookies to avoid getting blocked

Contributing

Search functionality needs work. If you figure out a way around Cloudflare's bot detection, please submit a PR.

Publishing to PyPI

To publish this package:

# Install build tools
pip install build twine

# Build the package
python -m build

# Upload to PyPI (you'll need PyPI account credentials)
python -m twine upload dist/*

For TestPyPI (testing):

python -m twine upload --repository testpypi dist/*

License

AGPL-3.0-or-later - Educational use only. Respect UG's ToS.

---

_{If you find this useful: Support via PayPal}