deprecate(3pm)

💖 NAME 💖

okay so this is deprecate — the Perl pragma for deprecating the inclusion of a module in core. it's from the Perl Programmers Reference Guide, and honestly it's giving "quietly saving your code from future chaos" energy 🫶

---

✨ SYNOPSIS ✨

use deprecate;  # warn about future absence if loaded from core

like, that's it. one line. iconic.

---

🌸 DESCRIPTION 🌸

bestie, here's the vibe: this pragma makes life so much easier when you're maintaining dual-life modules — yk, the ones that are gonna get dropped from the Perl core in some future Perl release but are still hanging out in core rn. 💅

the whole point? alert the user to what's going on with a warning that's basically like "hey, go install this from CPAN" — so that when they eventually upgrade to a perl that doesn't include the module, their code doesn't just break on them. no cap, that's the goal. 😭

but here's the cute part: that warning only fires if the module was loaded from a core library directory. which means you can totally put the use deprecate line inside the CPAN version of the module too. because the pragma stays silent when the module runs from a non-core library directory, you don't have to patch the call into or out of either the core version or the CPAN version. the exact same code ships for either purpose. one codebase, two jobs. main character energy fr fr ✨

⚠️ Important Caveat ⚠️

okay so pay attention here, this one matters 🚨

if a module installs from CPAN into a core library directory instead of the site library directories, the user gets zero protection from having installed it. literally none. 💀

and at the same time? this pragma cannot detect when a module has installed from CPAN to the core library — so it would just endlessly and uselessly exhort the user to upgrade. forever. for no reason. not the vibe. 🙈

so: modules that can install from CPAN to the core library have to make sure they don't call this pragma when they've done so. generally that means mirroring the exact logic from the installer inside the module itself. like this:

# Makefile.PL
WriteMakefile(
    # ...
    INSTALLDIRS => ( "$]" >= 5.011 ? 'site' : 'perl' ),
);

# lib/Foo/Bar.pm
use if "$]" >= 5.011, 'deprecate';

(the example above shows the most important case of this: when the target is a Perl older than 5.12 — where the core library directories take precedence over the site library directories — and the module being installed was included in core in that Perl version. under those circumstances, an upgrade of the module from CPAN is only possible by installing to the core library.) 🎀

---

🦋 EXPORT 🦋

none by default. the only method is import, and it gets called by use deprecate;. that's the whole squad. 🫶

---

🌈 SEE ALSO 🌈

the first example to use deprecate; was Switch. trendsetter behavior honestly 👑

---

🎀 AUTHOR 🎀

original version by Nicholas Clark 💜

---

⭐ COPYRIGHT AND LICENSE ⭐

Copyright (C) 2009, 2011

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available. slay, legal-wise 💅

---

okay that's the whole page!! this was perl v5.42.3, dated 2026-11-03, and it's the deprecate(3pm) page from the Perl Programmers Reference Guide — ty for reading bestie, go forth and deprecate responsibly 🌸🦋✨