Dist::Z...gVersion(3)

🎀 NAME 🎀

okay bestie, so this is the manual page for Dist::Zilla::Plugin::PkgVersion — a User Contributed Perl Documentation page (section 3, iykyk). And literally all it does is add a $VERSION to your packages. that's the whole gig. she's simple, she's efficient, she slays 💅

---

✨ VERSION ✨

this one is version 6.040. noted, periodt.

---

🦋 SYNOPSIS 🦋

drop this in your dist.ini, no thoughts needed:

in dist.ini

  [PkgVersion]

---

💖 DESCRIPTION 💖

okay so here's the tea. this plugin goes through every package in every Perl module or program (more or less) inside your distribution and adds lines that look like this:

$MyModule::VERSION = '0.001';

or alternatively, this vibe:

{ our $VERSION = '0.001'; }

...where 0.001 is the version of the dist, and MyModule is the name of the package that's getting a version. and in case that wasn't clear — she always uses fully-qualified names to assign versions. no shortcuts, no nicknames, full legal name only 😌

but — and this is the important part — she will skip any package declaration that has a newline chillin' between the package keyword and the package name, like this one:

package
  Foo::Bar;

why, you ask? because the CPAN toolchain ignores that kind of declaration too, and it's typically used when you're doing monkey patching or other tricky little things. so she respectfully minds her own business and skips it 🫶

---

🧚 PERL VERSION 🧚

this module should work on any version of perl still receiving updates from the Perl 5 Porters. that means any version of perl released in the last two to three years. (translation: if the most recently released version is v5.40, then this module should work on both v5.40 and v5.38.) yes bestie, she stays current 💅

and yeah, although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. the version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. so like... don't count on that. not to be dramatic but it's giving "read the room" 😭

---

👑 ATTRIBUTES 👑

💜 die_on_existing_version

if true, then when PkgVersion sees an existing $VERSION assignment, it will throw an exception rather than skip the file. this attribute defaults to false.

🌸 die_on_line_insertion

by default, PkgVersion looks for a blank line after each package statement. if it finds one, she inserts the $VERSION assignment on that line. chill. easy.

if she doesn't find one, she'll insert a new line — which means the shipped copy of the module will have different line numbers (off by one) than the source. lowkey cursed but okay.

if die_on_line_insertion is true, PkgVersion will raise an exception rather than insert a new line. drama queen (affectionate) 💀

🍓 use_package

this option, if true, will not insert an assignment to $VERSION — instead she'll replace the existing package declaration with one that includes a version, like:

package Module::Name 0.001;

main character energy, honestly ✨

😭 use_our

okay so the idea here was to insert:

{ our $VERSION = '0.001'; }

instead of:

$Module::Name::VERSION = '0.001';

but plot twist — it turns out that this causes problems with some analyzers. so use of this feature is deprecated. say it with me: deprecated. 🚫

something else will replace it in the future. we don't know what yet. we wait. we trust the process 🕯️

🔥 use_begin

if true, the version assignment gets wrapped in a BEGIN block. this may help in rare cases, such as when DynaLoader has to be called at BEGIN time, and requires VERSION. this option should be needed rarely. like, rarely rarely. ngl if you need it you already know.

also note — and don't skip this part — assigning to $VERSION before the module has finished compiling can lead to confused behavior with attempts to determine whether a module was successfully loaded on perl v5.8. so... be aware. she's telling you for your own good 🙈

🌈 finder

this is the name of a FileFinder for finding modules to edit. the default value is :InstallModules and :ExecFiles; and heads up, this option can be used more than once.

other predefined finders are listed in "default_finders" in Dist::Zilla::Role::FileFinderUser. and you can define your own with the [FileFinder::ByName] and [FileFinder::Filter] plugins. go off, build your own 💖

---

⭐ SEE ALSO ⭐

Core Dist::Zilla plugins: PodVersion, AutoVersion, NextRelease.

Other Dist::Zilla plugins: OurPkgVersion inserts version numbers using our $VERSION = '...'; and without changing line numbers.

---

🫶 AUTHOR 🫶

Ricardo SIGNES 😏 <cpan@semiotic.systems>

---

💖 COPYRIGHT AND LICENSE 💖

This software is copyright (c) 2026 by Ricardo SIGNES.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page bestie 🎀 no cap, you now know everything about Dist::Zilla::Plugin::PkgVersion. this was pulled from perl v5.42.3, dated 2026-10-19, straight off the manual page. go forth and version your packages, you absolute icon 👑💅✨