Use perlexperiment to Audit Perl Features Before You Depend on Them

By the end of this guide you will be able to inspect the experimental features known to your installed Perl, tell an accepted feature from a current experiment, and check a program for warnings before you put it into a script or service. The examples use Perl 5.38.2 from Ubuntu's perl-doc package. Allow about 10 minutes for a first pass, plus time to test on every Perl version you support.

Before you start

You need a shell, Perl itself, and the perl-doc package. The package supplies the perlexperiment(1) manual page; it does not install a command called perlexperiment. No root access is needed for the checks below.

perl -v
perldoc -l perlexperiment

On the machine used for this guide, the relevant output is:

This is perl 5, version 38, subversion 2 (v5.38.2)
/usr/share/perl/5.38/pod/perlexperiment.pod

1. Read the local inventory

Open the reference with perldoc or the manpage viewer. The page is an inventory, not a feature switch and not a test runner. It groups entries into current experiments, accepted features, and removed features, then records introduction, modification, acceptance, deprecation, or removal versions where Perl documents them.

perldoc perlexperiment

# The same page in a terminal manpage viewer
man 1 perlexperiment

For a quick, non-interactive excerpt:

perldoc -T perlexperiment | sed -n '/Current experiments/,/Accepted features/p' | sed -n '1,90p'

The exact inventory belongs to the Perl release that supplied the documentation. Do not copy a feature's status from a different machine and assume it applies here. This local page identifies smart match (~~) as deprecated in Perl 5.38.0 and scheduled for removal in 5.42.0. It also lists newer experiments such as try/catch, the builtin namespace, defer, and multiple iteration variables.

2. Separate status from availability

An entry in the current-experiments section is a warning about compatibility and stability, not proof that the syntax is enabled by default. For example, the local page says that aliasing via reference uses the experimental::refaliasing warning category. The corresponding experiment may be present in this interpreter, absent in an older one, or changed in a later one.

Accepted features are different. They started life as experiments but are now part of Perl's stable feature set. Their presence in perlexperiment is historical context, not a recommendation to enable an experimental warning category. Removed features are a migration warning: an old program may still mention them even though a current Perl cannot use them.

Use the feature's own manual page for syntax and semantics. Use perlexperiment to answer the narrower questions: when did it appear, what is its status in this release, and which warning category should you look for?

3. Turn the entry into a compatibility check

Start with warnings enabled and compile the real source without running it. The -c option checks syntax, while -w enables warnings for the check. Replace the placeholder with a copy of the file you intend to deploy.

perl -w -c ./YOUR_SCRIPT.pl

Expected success is a line like this:

./YOUR_SCRIPT.pl syntax OK

A warning such as experimental::try or deprecated is evidence to investigate, not output to hide. Read the relevant feature page, decide which minimum Perl version you support, and test that decision in your build or deployment checks. Do not silence all warnings merely to make this command green: that removes the signal you are trying to audit.

To make one warning category visible while checking a small probe, use the category named by the manual page:

perl -Mwarnings=experimental::try -e 'use experimental "try"; print "probe ran\n"'

The probe should print probe ran. The important result is whether your target Perl accepts the syntax and whether the warning policy is understood. A category name is not a portable feature test by itself; pair it with compilation or a deliberately small runtime test.

4. Check version boundaries explicitly

When a page gives an introduction or removal version, encode that boundary in a test rather than relying on the machine where development happened. This simple shell check compares Perl's numeric version with a required minimum:

perl -e 'die "Perl 5.36 or newer is required\n" if $^V lt v5.36.0; print "$^V accepted\n"'

Do not use this as a substitute for testing the feature. It only checks the interpreter version. A distribution may backport patches, and a program may require a feature that is present but still experimental. Compile the actual file with warnings after the version guard.

For a removal such as smart match, search the source and review each match before upgrading:

rg -n --fixed-strings '~~' ./YOUR_PROJECT

This search can find comments and strings as well as operators, so it is a review starting point, not a parser. If the matches include executable smart-match expressions, plan a replacement before moving to a Perl release that removes them.

Common traps and recovery

• Confusing the document with a command: perlexperiment is the manual page name. Use perldoc or man to read it.
• Reading the wrong release: check both perl -v and perldoc -l perlexperiment. A mixed installation can pair one interpreter with another release's documentation.
• Treating accepted as experimental: accepted entries are historical. Follow the feature's normal documentation and do not add an unnecessary experimental pragma.
• Ignoring warnings because syntax works: an experimental construct can compile today and still change or disappear. Keep the warning visible in CI.
• Testing only one interpreter: run the same compile and test commands against every supported Perl release. If a check fails, undo no system change is required: remove only the new code or restore the source from version control, then rerun the checks.

Done means

• You recorded the installed Perl version.
• You read the local perlexperiment(1) page from the matching documentation package.
• You know whether the feature is current, accepted, deprecated, or removed in that release.
• Your real source compiles with warnings enabled.
• Your supported Perl versions and upgrade plan cover every experimental or removal boundary you found.