Mac::Finder::Tags - Access macOS file tags (aka Finder labels)


version 0.01


 my $ft = Mac::Finder::Tags->new();
 # optional caching of all tagged files on startup
 my $ft = Mac::Finder::Tags->new( caching => 1 );
 # manually choose an implementation variant
 my $ft = Mac::Finder::Tags->new( impl => 'mdls' );
 my $ft = Mac::Finder::Tags->new( impl => 'xattr' );
 # read tags from a file
 my @tags = $ft->get_tags( $path );
 # obtain tag details
 my $name  = $tag->name;
 my $color = $tag->color;
 my $flags = $tag->flags;  # Finder label flags (numeric color code)
 my $emoji = $tag->emoji;  # an Emoji approximating the color
 my $is_legacy  = $tag->legacy_label;   # legacy Finder label
 my $is_guessed = $tag->color_guessed;  # color is uncertain or
                                        # undetermined (mdls only)
 # modify tags of a file
 my $tag1 = $ft->tag( 'Important', 'orange' );
 my $tag2 = $ft->tag( 'Client 276' );
 $ft->set_tags( $path, @tags );
 $ft->add_tags( $path, @tags );
 $ft->remove_tags( $path, @tags );
 # list all tags defined on the system
 my @tags = $ft->all_tags();
 # search entire system for files by tag
 my @files = $ft->find_files_all( @tags );
 my @files = $ft->find_files_any( @tags );


This class offers methods to read and write macOS file system tags (the feature that replaced Mac OS Finder labels from OS X 10.9).

It is also an attempt to put Object::Pad to some use. As such, all the warnings about the experimental status of Object::Pad apply directly to this module as well.

This software has pre-release quality. There is little documentation and no schedule for further development.


The implementation based on mdls is much faster than the one based on xattr. However, mdls doesn't provide the color of tags for files that have multiple tags. This issue is mitigated to some extent when caching is enabled.

When caching is enabled, all tags on the entire system will be cached using mdfind at object creation time. get_tags() will then only perform lookups in this cache, which is extremely fast. You should consider caching whenever you intend to look up more than maybe a hundred or so files; however, if your system has an extremely large number of tagged files or a large number of different tags, cache creation may cause a significant delay. You may wish to run your own performance tests for your environment.

By default, this module will use mdls when caching is disabled, and xattr when caching is enabled (in which case the speed difference doesn't matter as much).


The semantics of tags without color (legacy Finder labels flag 0) and tags with no defined color (because it is undetermined or unknown) are not yet clearly differentiated.

The following methods are unimplemented in this version:

  • add_tags

  • set_tags

  • find_files_all

  • find_files_any

  • remove_tags

This software may not work on other filesystems than HFS+ or APFS. So far, it has only been tested on macOS 10.15.


Arne Johannessen <>

If you contact me by email, please make sure you include the word "Perl" in your subject header to help beat the spam filters.


This software is Copyright (c) 2022 by Arne Johannessen.

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0 or (at your option) the same terms as the Perl 5 programming language system itself.