webloc

webloc is a Ruby library that can read from and write to .webloc files as used on macOS. These are a variant of 'plist' format files, specifically used for storing links to URLs.

It works on Ruby 3.0 and up (including Ruby 4.0.2 and TruffleRuby). It reads XML and binary plist files and writes binary plist files, supporting Unicode and URLs longer than 65,535 characters.

gem install webloc

Reading a .webloc file:

require 'webloc'
webloc = Webloc.load('bookmark.webloc')
puts webloc.url
# => "https://example.com"

Writing to a .webloc file:

require 'webloc'
Webloc.new('https://rubyweekly.com/').save('rubyweekly.webloc')

require 'webloc'

begin
  webloc = Webloc.load('suspicious.webloc')
  puts webloc.url
rescue Webloc::FileNotFoundError => e
  puts "File not found: #{e.message}"
rescue Webloc::CorruptedFileError => e
  puts "File is corrupted: #{e.message}"
rescue Webloc::InvalidFormatError => e
  puts "Invalid file format: #{e.message}"
rescue Webloc::WeblocError => e
  puts "General webloc error: #{e.message}"
end

require 'webloc'
require 'uri'

def create_webloc_safely(url, filename)
  # Basic URL validation
  uri = URI.parse(url)
  unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
    puts "Invalid URL scheme: #{url}"
    return false
  end
  
  # Create the webloc file
  Webloc.new(url).save(filename)
  puts "Created #{filename} for #{url}"
  true
rescue URI::InvalidURIError
  puts "Invalid URL format: #{url}"
  false
rescue Webloc::WeblocError => e
  puts "Failed to create webloc: #{e.message}"
  false
end

create_webloc_safely('https://example.com', 'example.webloc')
create_webloc_safely('invalid-url', 'invalid.webloc')

require 'webloc'
require 'json'

# Convert webloc to JSON
webloc = Webloc.load('bookmark.webloc')
json_data = { url: webloc.url, title: File.basename('bookmark.webloc', '.webloc') }
File.write('bookmark.json', JSON.pretty_generate(json_data))

# Convert JSON back to webloc
json_content = JSON.parse(File.read('bookmark.json'))
Webloc.new(json_content['url']).save('restored.webloc')

The public methods and error classes are unchanged. The reader also recovers historical long-URL files with the known offset bugs. New writes correct those offsets; short ASCII URLs retain their original binary encoding. Binary reading supports short URLs, additional metadata, and different object orders. URLs are stored as supplied, without escaping or scheme validation. Unicode strings use UTF-16 in binary files and are returned as UTF-8 when read.

Malformed files without a recoverable historical layout raise a WeblocError subclass instead of returning a partial URL.

Run bundle install followed by bundle exec rake test.

The suite retains the original tests and fixtures and exercises the Ruby examples in this README. Additional fixtures cover other binary layouts and files written by older releases. Interoperability tests use Python 3's plistlib when available and Apple's plutil on macOS; neither is a runtime dependency of the gem.

Thanks is due to Christos Karaiskos for this article which helped me understand the plist format a bit more when fixing a bug in 2024.

Copyright (C) 2011-2026 Peter Cooper

webloc is licensed under the terms of the MIT License