Skip to main content

Social Links

License Tests Python PyPI PyPI Downloads Documentation Interactive Demo Author site Context7 Ask DeepWiki

Python library to validate, sanitize, and detect social media URLs. Support for LinkedIn, Instagram, TikTok, X/Twitter, GitHub, Facebook, YouTube, and 240+ platforms. Features automatic URL normalization and zero dependencies. Easy to use, regex-powered, and customizable.

🚀 Try it interactively in your browser! Test the library with our Interactive Demo - no installation required.

OG Image

Features

  • 🔍 Auto-detect social media platforms from URLs
  • ✅ Validate URLs against specific platforms
  • 🧹 Sanitize URLs to canonical format
  • 🆔 Extract IDs (usernames, profile IDs) from URLs
  • 🎯 240+ predefined platforms (LinkedIn, GitHub, Twitter/X, Facebook, Instagram, YouTube, and more)
  • 🔧 Customizable - Add your own platforms with regex patterns
  • 🚀 Zero dependencies - Pure Python, no external libraries

Installation

pip install social-links

Or using uv:

uv pip install social-links

Quick Start

from sociallinks import detect_platform, sanitize, extract_id, is_valid, list_platforms

# Detect platform from URL
platform = detect_platform("https://www.linkedin.com/in/ysskrishna/")
print(platform)  # "linkedin"

# Validate URL for a specific platform
is_valid_url = is_valid("linkedin", "https://www.linkedin.com/in/ysskrishna/")
print(is_valid_url)  # True

# Sanitize URL to canonical format
sanitized = sanitize("linkedin", "https://www.linkedin.com/in/ysskrishna/")
print(sanitized)  # "https://linkedin.com/in/ysskrishna"

# Extract username/ID from URL
user_id = extract_id("linkedin", "https://www.linkedin.com/in/ysskrishna/")
print(user_id)  # "ysskrishna"

# List all supported platforms
platforms = list_platforms()
print(f"Supported platforms: {len(platforms)}")  # Supported platforms: 240+

That's it! For most use cases, you don't need anything more. See Basic Usage for more examples, or Advanced Usage if you need custom platforms or configurations.

Supported Platforms

The library comes with 240+ predefined platforms:

Show all supported platforms
Predefined Platforms
500px About.me Airbnb
Ameba Blog Anaconda.org AniList
Apple Music Are.na ArtStation
AtCoder Audioboom Audiomack
Bandcamp Beacons Behance
Bilibili Bio.link BitChute
Blogger Bluesky Brunch
Bugcrowd Buttondown Buy Me a Coffee
Campsite.bio Cara Carrd
Character.AI Chess.com Chub.ai (NSFW)
CHZZK Civitai ClawHub
Codeberg Codecademy CodeChef
Codeforces Codementor CodePen
CodeSandbox Codewars Contra
Coursera crates.io Crunchbase
CSDN CurseForge Dailymotion
Depop Dev.to DeviantArt
Discogs Discord Docker Hub
Douban Douyin Douyu
Dribbble Dzen eBay
Etsy Exercism Facebook
FACEIT Fanfix (NSFW) Farcaster
Figma Fiverr Flickr
Flipboard freeCodeCamp Freelancer.com
Fur Affinity (NSFW) Game Jolt GeeksforGeeks
Genius Gitee GitHub
GitLab GOG Goodreads
Google Scholar Gravatar Gumroad
Habr Hacker News HackerEarth
HackerOne HackerRank Hashnode
Hatena Blog Hex Hey.xyz
Hoo.be Hugging Face Huya
Imgur iNaturalist Indie Hackers
Instagram Instructables Issuu
itch.io Jamendo Juejin
Kaggle KakaoTalk Channel Keybase
Khan Academy Kick Kickstarter
Ko-fi Komoot Kuaishou
Last.fm Launchpad LeetCode
Lemmy World Lemon8 Letterboxd
Liberapay Lichess LINE
LinkedIn (personal & company) Linktree Lobsters
Malt Mastodon Medium
Mercari MetaCPAN Minds
Misskey Mixcloud Modrinth
MyAnimeList Myspace Naver Blog
Niconico Nimo TV note
npm NuGet Odysee
OK.ru Ollama OnlyFans (NSFW)
Open Collective OpenSea OpenStreetMap
ORCID OSF osu!
Packagist Paragraph Patreon
Pexels Pinterest Pixelfed
Pixiv Poshmark Primal
Product Hunt PyPI Qiita
Quora RateYourMusic Redbubble
Reddit Replicate Replit
ResearchGate Roblox Royal Road
RubyGems Rumble Rutube
Scratch Scribd Semantic Scholar
ShareChat Signal Sketchfab
Slashdot SlideShare Snapchat
solo.to SOOP (AfreecaTV) SoundCloud
SourceForge SourceHut Speedrun.com
Spotify Stack Exchange Stack Overflow
Stan Store start.gg Steam
Substack Taplink Telegram
The StoryGraph Thingiverse Threads
Throne (NSFW) TikTok Tistory
TMDB Topcoder Topmate
Toyhouse Trakt Trello
Tripadvisor Trustpilot Truth Social
TryHackMe Tumblr Twitch
Udemy Unsplash Untappd
Velog Vimeo Vinted
VK Wattpad WeChat
Weibo Weights & Biases Wellfound (AngelList)
WhatsApp WordPress WordPress.org
X (Twitter) XDA Forums Xiaohongshu (RedNote)
XING YouTube Zenn

Basic Usage

The simplest way to use social-links is with module-level functions. These work out of the box with 240+ predefined platforms - no configuration needed!

Detect Platform

from sociallinks import detect_platform

# Detect from full URL
detect_platform("https://github.com/ysskrishna")  # "github"
detect_platform("https://x.com/ysskrishna")      # "x"
detect_platform("https://example.com")           # None

# Works with various URL formats
detect_platform("http://linkedin.com/in/ysskrishna")
detect_platform("www.facebook.com/ysskrishna")
detect_platform("  https://instagram.com/ysskrishna  ")  # Handles whitespace

# Share links with tracking parameters or fragments are accepted
detect_platform("https://www.instagram.com/ysskrishna/?igsh=abc")  # "instagram"
detect_platform("https://github.com/ysskrishna?tab=repositories")  # "github"

# A bare username does not identify a platform
detect_platform("ysskrishna")                    # None

Validate URLs

from sociallinks import is_valid

# Validate against specific platform
is_valid("linkedin", "https://www.linkedin.com/in/ysskrishna/")  # True
is_valid("linkedin", "https://example.com")                   # False
is_valid("github", "https://github.com/ysskrishna")             # True

# A bare username is valid for the platform you name
is_valid("github", "ysskrishna")                                # True

# The URL must start with the platform's URL (no embedded URLs)
is_valid("github", "https://evil.com/?r=https://github.com/ysskrishna")  # False

Sanitize URLs

from sociallinks import sanitize

# Normalize to canonical format
sanitize("linkedin", "https://www.linkedin.com/in/ysskrishna/")
# Returns: "https://linkedin.com/in/ysskrishna"

sanitize("github", "http://www.github.com/ysskrishna")
# Returns: "https://github.com/ysskrishna"

sanitize("x", "https://twitter.com/ysskrishna")
# Returns: "https://x.com/ysskrishna"

Extract IDs

from sociallinks import extract_id

# Extract username/profile ID from URL
extract_id("linkedin", "https://www.linkedin.com/in/ysskrishna/")  # "ysskrishna"
extract_id("github", "https://github.com/ysskrishna")              # "ysskrishna"
extract_id("x", "https://twitter.com/ysskrishna")                  # "ysskrishna"

# Works with company/org URLs too
extract_id("linkedin", "https://linkedin.com/company/acme")  # "acme"

List Platforms

from sociallinks import list_platforms

# Get all available platforms
platforms = list_platforms()
# Returns: ["behance", "dev_to", "dribbble", "github", "linkedin", ...]
print(f"Supported platforms: {len(platforms)}")  # 240+

Advanced Usage

For custom configurations, custom platforms, or programmatic platform management, use the SocialLinks class directly instead of the module-level functions.

When to Use Advanced Features

Use the class API when you need to:

  • Add support for platforms not in the predefined list
  • Customize how existing platforms are detected or sanitized
  • Manage platforms programmatically (add, remove, modify)
  • Configure regex flags or start with an empty platform list

Using the Class API

The SocialLinks class provides the same methods as module-level functions, but with additional configuration options:

from sociallinks import SocialLinks

sl = SocialLinks()

# Same methods as module functions
sl.detect_platform("https://github.com/ysskrishna")  # "github"
sl.is_valid("linkedin", "https://linkedin.com/in/user")  # True
sl.sanitize("github", "https://github.com/user")  # "https://github.com/user"
sl.extract_id("github", "https://github.com/user")  # "user"
sl.list_platforms()  # ["behance", "dev_to", "dribbble", ...]

Configuration Options

from sociallinks import SocialLinks

import re

# Start with empty platform list (useful for custom platforms only)
sl = SocialLinks(use_predefined_platforms=False)

# Configure regex compilation flags
sl = SocialLinks(regex_flags=re.IGNORECASE | re.MULTILINE)

Understanding Platform Configuration
Platform configuration structure and key concepts

A platform configuration is a list of dictionaries. Each dictionary contains:

  • patterns: List of regex patterns that match URLs for this platform
  • sanitized: Template string for the canonical URL format

Multiple dictionaries are useful when a platform has different URL types that normalize to different canonical forms (e.g., LinkedIn personal profiles /in/ vs company pages /company/).

Configuration Structure

Single dictionary - Multiple patterns sharing the same sanitization template:

platform_config = [{
    "patterns": [
        r"https?://(www\.)?example\.com/(?P<id>[A-Za-z0-9_]+)/?$",
        r"https?://example\.com/user/(?P<id>[A-Za-z0-9_]+)/?$"
    ],
    "sanitized": "https://example.com/{id}"
}]

Multiple dictionaries - Different URL formats with different sanitization templates (e.g., personal profiles vs company pages):

# Example: LinkedIn supports both personal profiles and company pages
platform_config = [
    {
        "patterns": [
            r"https?://(www\.)?linkedin\.com/in/(?P<id>[A-Za-z0-9_-]+)/?$",
            r"https?://linkedin\.com/mwlite/in/(?P<id>[A-Za-z0-9_-]+)/?$"
        ],
        "sanitized": "https://linkedin.com/in/{id}"  # Personal profiles
    },
    {
        "patterns": [
            r"https?://(www\.)?linkedin\.com/company/(?P<id>[A-Za-z0-9_-]+)/?$",
            r"https?://(www\.)?linkedin\.com/school/(?P<id>[A-Za-z0-9_-]+)/?$"
        ],
        "sanitized": "https://linkedin.com/company/{id}"  # Company/school pages
    }
]

Key Concepts

Pattern Matching:

  • Use named groups like (?P<id>...) to capture identifiers (username, ID, etc.)
  • For detect_platform(): Platforms are checked in registration order and the first match is returned
  • For sanitize(): Patterns are checked in order, and the first match is used

Sanitization Template:

  • Use {id} (or other named groups from patterns) as placeholders
  • This defines the canonical URL format returned by sanitize()
  • The template must contain {id} and no other placeholder; otherwise set_platform() raises InvalidPlatformError

URL handling:

  • Patterns are matched from the start of the input, so end URL patterns with /?$
  • If nothing matches, the input is tried again without its query string and fragment, so share links work
  • Patterns that are only a bare ID (such as ^{PROFILE_ID}$, built from sociallinks.constants) are skipped by detect_platform() but still accepted by is_valid(), sanitize() and extract_id()

Adding Custom Platforms

Basic Example

from sociallinks import SocialLinks

sl = SocialLinks(use_predefined_platforms=False)

# Define a custom platform
custom_platform = [{
    "patterns": [
        r"https?://(www\.)?example\.com/(?P<id>[A-Za-z0-9_]+)/?$",
        r"https?://example\.com/user/(?P<id>[A-Za-z0-9_]+)/?$"
    ],
    "sanitized": "https://example.com/{id}"
}]

# Register the platform
sl.set_platform("example", custom_platform)

# Use it
sl.detect_platform("https://example.com/user123")  # "example"
sl.sanitize("example", "https://www.example.com/user123/")  # "https://example.com/user123"
Handling multiple URL formats

Handling Multiple URL Formats

When a platform supports different URL formats that normalize to different canonical forms (e.g., personal profiles vs company pages):

from sociallinks import SocialLinks

sl = SocialLinks(use_predefined_platforms=False)

# Example: Platform with personal profiles and company pages
linkedin_style_platform = [
    {
        "patterns": [
            r"https?://(www\.)?example\.com/profile/(?P<id>[A-Za-z0-9_-]+)/?$",
            r"https?://(www\.)?example\.com/user/(?P<id>[A-Za-z0-9_-]+)/?$"
        ],
        "sanitized": "https://example.com/profile/{id}"  # Personal profiles
    },
    {
        "patterns": [
            r"https?://(www\.)?example\.com/company/(?P<id>[A-Za-z0-9_-]+)/?$",
            r"https?://(www\.)?example\.com/org/(?P<id>[A-Za-z0-9_-]+)/?$"
        ],
        "sanitized": "https://example.com/company/{id}"  # Company pages
    }
]

sl.set_platform("example", linkedin_style_platform)

# Personal profile URLs normalize to /profile/
sl.sanitize("example", "https://www.example.com/user/johndoe")  
# Returns: "https://example.com/profile/johndoe"

# Company URLs normalize to /company/
sl.sanitize("example", "https://www.example.com/org/acme-corp")  
# Returns: "https://example.com/company/acme-corp"

Managing Platforms
View, add, modify and remove platforms

Viewing Platform Configurations

from sociallinks import SocialLinks

sl = SocialLinks()

# Get configuration for an existing platform
github_config = sl.get_platform("github")
print(github_config)  # See the patterns and sanitized template

# List all available platforms
platforms = sl.list_platforms()
# Returns: ["behance", "dev_to", "dribbble", "github", "linkedin", ...]

Adding Platforms

from sociallinks import SocialLinks

sl = SocialLinks()

# Add a new platform (raises error if platform already exists)
custom_platform = [{
    "patterns": [r"https?://example.com/(?P<id>[A-Za-z0-9_]+)"],
    "sanitized": "https://example.com/{id}"
}]
sl.set_platform("example", custom_platform)

# Override an existing platform (including predefined ones)
sl.set_platform("github", custom_platform, override=True)

Adding Multiple Platforms

from sociallinks import SocialLinks

sl = SocialLinks()

# Add multiple platforms at once
new_platforms = {
    "platform1": [{
        "patterns": [r"https?://example1.com/(?P<id>[A-Za-z0-9_]+)"],
        "sanitized": "https://example1.com/{id}"
    }],
    "platform2": [{
        "patterns": [r"https?://example2.com/(?P<id>[A-Za-z0-9_]+)"],
        "sanitized": "https://example2.com/{id}"
    }]
}

sl.set_platforms(new_platforms, override=False)  # Raises error if any exist
sl.set_platforms(new_platforms, override=True)   # Overrides existing platforms

Modifying Existing Platforms

from sociallinks import SocialLinks

sl = SocialLinks()

# Get existing configuration
github_config = sl.get_platform("github")

# Modify and override
custom_github = [{
    "patterns": [r"https?://github\.com/(?P<id>[A-Za-z0-9_]+)/?$"],
    "sanitized": "https://github.com/{id}"
}]
sl.set_platform("github", custom_github, override=True)

Removing Platforms

from sociallinks import SocialLinks

sl = SocialLinks()

# Delete a single platform
sl.delete_platform("custom_platform")

# Delete multiple platforms
sl.delete_platforms(["platform1", "platform2"])

# Clear all platforms
sl.clear_platforms()

Registration is all-or-nothing: if a configuration is invalid, set_platform() and set_platforms() raise and leave the existing platforms untouched.

Complete Example
Build a custom platform manager

Here's a complete example showing how to build a custom platform manager:

from sociallinks import is_valid

from sociallinks import SocialLinks

# Start with predefined platforms
sl = SocialLinks()

# Add a custom platform
my_platform = [{
    "patterns": [
        r"https?://(www\.)?mysite\.com/profile/(?P<id>[A-Za-z0-9_]+)/?$",
        r"https?://(www\.)?mysite\.com/u/(?P<id>[A-Za-z0-9_]+)/?$"
    ],
    "sanitized": "https://mysite.com/profile/{id}"
}]
sl.set_platform("mysite", my_platform)

# Use it
url = "https://www.mysite.com/u/johndoe"
platform = sl.detect_platform(url)  # "mysite"
sanitized = sl.sanitize(platform, url)  # "https://mysite.com/profile/johndoe"
user_id = sl.extract_id(platform, url)  # "johndoe"
is_valid = sl.is_valid(platform, url)  # True

# View all platforms
all_platforms = sl.list_platforms()
print(f"Total platforms: {len(all_platforms)}")

API Reference

Every public function, SocialLinks method and exception, with parameters, return values and examples, is listed in API.md.

Roadmap

Planned improvements
  • Add method to configure custom sanitization patterns
  • Lint with ruff in CI
  • Add a formatter (black or ruff format) and isort-style import sorting
  • Add code coverage reporting with pytest-cov
  • Refactor platform entries using dataclasses for better structure

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct, development setup, and the process for submitting pull requests.

Credits

This package is inspired by the social-links npm package by gkucmierz.

Built and maintained by

Social Links is built and maintained by:

Name GitHub Role
Y. Siva Sai Krishna Y. Siva Sai Krishna @ysskrishna Creator

Changelog

See CHANGELOG for release history.

Support

If you find this library helpful:

License

MIT © Y. Siva Sai Krishna — see LICENSE for details.


Author's GitHub • Author's LinkedIn • Author's site • Package on PyPI • ClawHub • Package Documentation • Interactive Demo • Report Issues

Metadata

Release files for social-links 1.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for social-links 1.5.0
File Size Uploaded Provenance Actions
social_links-1.5.0.tar.gz 477.9 kB Without provenance Details for social_links-1.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for social-links 1.5.0
File Interpreter ABI Platform Actions
social_links-1.5.0-py3-none-any.whl Python 3 none any Details for social_links-1.5.0-py3-none-any.whl

Total release size: 508.7 kB

Security for social-links 1.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page