---
name: "Perl::Critic::Policy::Subroutines::ProhibitUnusedPrivateSubroutines"
section: "3pm"
platform: "linux"
package: "perl-perl-critic"
version: "1.156-3"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Perl::Critic::Policy::Subroutines::ProhibitUnusedPrivateSubroutines"
---

# Perl::Critic::Policy::Subroutines::ProhibitUnusedPrivateSubroutines(3pm)

Prevent unused private subroutines.

## NAME

Perl::Critic::Policy::Subroutines::ProhibitUnusedPrivateSubroutines - Prevent unused private subroutines.

## AFFILIATION

This Policy is part of the core Perl::Critic distribution.

## DESCRIPTION

By convention Perl authors (like authors in many other languages) indicate private methods and variables by inserting a leading underscore before the identifier.  This policy catches such subroutines which are not used in the file which declares them.

This module defines a 'use' of a subroutine as a subroutine or method call to it (other than from inside the subroutine itself), a reference to it (i.e. `"my $foo = \&_foo"`), a `"goto"` to it outside the subroutine itself (i.e. `"goto &_foo"`), or the use of the subroutine's name as an even-numbered argument to `"use overload"`.

## CONFIGURATION

You can define what a private subroutine name looks like by specifying a regular expression for the `"private_name_regex"` option in your *.perlcriticrc*:

```
    [Subroutines::ProhibitUnusedPrivateSubroutines]
    private_name_regex = _(?!_)\w+
```

The above example is a way of saying that subroutines that start with a double underscore are not considered to be private.  (Perl::Critic, in its implementation, uses leading double underscores to indicate a distribution-private subroutine -- one that is allowed to be invoked by other Perl::Critic modules, but not by anything outside of Perl::Critic.)

You can configure additional subroutines to accept by specifying them in a space-delimited list to the `"allow"` option:

```
    [Subroutines::ProhibitUnusedPrivateSubroutines]
    allow = _bar _baz
```

These are added to the default list of exemptions from this policy. So the above allows `"sub _bar {}"` and `"sub _baz {}"`, even if they are not referred to in the module that defines them.

You can allow a whole class or subroutine names by defining a regular expression that matches allowed names.

```
    [Subroutines::ProhibitUnusedPrivateSubroutines]
    allow_name_regex = _build_\w+
```

You can configure this policy not to check private subroutines declared in a file that uses one or more particular named modules.  This allows you to, for example, exclude unused private subroutine checking in classes that are roles.

```
    [Subroutines::ProhibitUnusedPrivateSubroutines]
    skip_when_using = Moose::Role Moo::Role Role::Tiny
```

## HISTORY

This policy is derived from Perl::Critic::Policy::Subroutines::ProtectPrivateSubs, which looks at the other side of the problem.

## BUGS

Does not forbid `"sub Foo::_foo{}"` because it does not know (and can not assume) what is in the `"Foo"` package.

Does not respect the scope caused by multiple packages in the same file.  For example a file:

```
    package Foo;
    sub _is_private { print "A private sub!"; }
    package Bar;
    _is_private();
```

Will not trigger a violation even though `"Foo::_is_private"` is not called. Similarly, `"skip_when_using"` currently works on a *file* level, not on a *package scope* level.

## SEE ALSO

Perl::Critic::Policy::Subroutines::ProtectPrivateSubs.

## AUTHOR

Chris Dolan \<cdolan@cpan.org\>

## COPYRIGHT

Copyright (c) 2009-2021 Thomas R. Wyant, III.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  The full text of this license can be found in the LICENSE file included with this module.