Use perldeprecation to audit ageing Perl code

You will finish with a version-aware list of Perl features that may need changing, plus a quick way to verify the documentation installed on your Linux machine. This guide uses the perldeprecation manual from the perl-doc package. It is documentation, not a program that scans a directory or rewrites source files.

Allow about 15 minutes for a first pass through a codebase. You need a shell, Perl and permission to read the source you are reviewing. No elevated privileges are needed unless the manual page is not installed and you choose to add the distribution's documentation package.

1. Check the Perl version and documentation package

Start by recording the interpreter version. Deprecation status is version-specific, so a warning or failure seen on one host is not automatically evidence about another.

perl -e 'print $^V, "\n"'
dpkg-query -W -f='${Package} ${Version}\n' perl-doc perl-base 2>/dev/null

On the machine used for this guide, the interpreter reports v5.38.2. The installed manual page is dated 2026-09-14 and identifies itself as Perl v5.38.2. Your package revision and manual date may differ.

2. Open the reference in the format you prefer

Use man for the normal terminal view, or perldoc when you want Perl's Pod text without the pager.

man perldeprecation
perldoc -T perldeprecation

Both commands should begin with the name and description, then group entries by the Perl release in which a feature was removed or made fatal. The manual also has an unscheduled section for changes whose removal release is not fixed.

A common distraction is looking for a runnable command named perldeprecation. There is no such executable in this installation. If perldeprecation returns "command not found", use man perldeprecation or perldoc -T perldeprecation instead.

3. Read the version headings before the individual entries

Each heading describes the point at which the change became fatal, disappeared or was scheduled to disappear. Do not treat every entry as an action for today. Some items are historical compatibility notes, while the unscheduled entries are the ones most likely to affect future upgrades.

For example, the local manual lists smartmatch, when, given and the ~~ operator under Perl 5.42, with category deprecated::smartmatch. It also records that using an apostrophe as a package name separator would stop being recognised in that release. In contrast, File::Glob::glob() is already removed in Perl 5.32 and should be replaced with File::Glob::bsd_glob().

The current upstream documentation may contain newer release headings than an older local package. Treat the local manual as the behaviour of the host you are maintaining, then compare it with the official Perl documentation when planning an upgrade.

4. Search your source for high-impact patterns

Search is a triage tool, not a proof that a match is unsafe. Run it from the project root and review each match in context.

rg -n --glob '*.pl' --glob '*.pm' \
  '(^|[^[:alnum:]_])(\$\*|\$#|\$\[|given|when|~~|File::Glob::glob|dump\s*\()' .

On older projects also search for unescaped literal left braces in regular expressions, byte operations involving code points above 0xFF, and calls that use sysread, recv, syswrite or send on a :utf8 handle. These cases need more careful parsing than a single regular expression can provide.

Do not edit a match just because it appears in the list. The manual distinguishes, for example, the obsolete $* multiline switch from the supported /m regular-expression modifier, and recommends printf or sprintf instead of the old numeric formatting variable $#.

5. Test a proposed replacement without changing the project

Use a temporary one-liner or a copy of the relevant test. This keeps the audit read-only and makes failures easy to discard.

perl -we 'my $pattern = qr/\{/; print "replacement compiles\n"'
perl -MFile::Glob=bsd_glob -we 'print join("\n", bsd_glob("*.pm")), "\n"'

The first example uses an escaped literal brace. The second calls the replacement API named by the manual. The output depends on the files in the current directory, so an empty result can be normal. Run the command in a safe checkout, not in a directory where a wildcard could expose confidential filenames.

For code that mixes Perl versions, run the project's test suite with every supported interpreter. A construct that is merely deprecated can become a compile-time error later, and a construct already removed cannot be made safe by silencing warnings.

6. Keep the audit focused

Record four things for each finding: the source location, the Perl version named by the manual, the replacement or rewrite, and the test that proves equivalent behaviour. Give unscheduled entries a separate follow-up label. This avoids spending time on old items that cannot occur in your supported versions while leaving future upgrade risks untracked.

Do not suppress deprecation warnings globally as a fix. That hides useful evidence from CI and production logs. If a dependency is responsible, update or replace it where possible, and document any temporary exception with the exact Perl version and test coverage.