FindBin(3pm)

📦
version 5.42.3 · 9 versions
, in alpine 3.24

🌸 FindBin(3pm) — like, the actual manual page, bestie 💅

Okay so this is FindBin, straight out of the Perl Programmers Reference Guide (section 3pm, iykyk). Buckle up, it's short but it eats. ✨

✨ NAME ✨

FindBin — lowkey the module that finds the directory your original Perl script is living in. That's the whole vibe. 🎀

🦋 SYNOPSIS 🦋

The main character setup, fr fr:

use FindBin;
use lib "$FindBin::Bin/../lib";

use FindBin qw($Bin);
use lib "$Bin/../lib";

Two ways, same energy. Pick your fave. 💖

🌈 DESCRIPTION 🌈

So basically FindBin locates the full path to the script's bin directory, which lets you use paths that are relative to that bin directory. Iconic behavior, honestly. 🫶

Why do you care? Because now a user can set up a directory tree for some software with directories <root>/bin and <root>/lib, and then the example up in SYNOPSIS lets you use modules in the lib directory without knowing where the software tree is installed. No cap, that's the whole point. ✨

🚨 Edge case alert: if perl is invoked using the -e option, or the Perl script is read from STDIN, then FindBin sets both $Bin and $RealBin to the current directory. Not the script's dir. There is no script. Adjust expectations accordingly. 💀

👑 EXPORTABLE VARIABLES 👑

Here's the squad you can import:

  • $Bin or $Dir — path to the bin directory from where the script was invoked 🗂️
  • $Script — the basename of the script from which perl was invoked 📜
  • $RealBin or $RealDir — $Bin with all links resolved 🔗
  • $RealScript — $Script with all links resolved 🔗

And if you're feeling greedy (valid), you can use the ALL tag to export every single one of the above together:

use FindBin ':ALL';

All the variables. One tag. Main character energy tbh. 💅

💀 KNOWN ISSUES 💀

Okay bestie, listen, this is the important part, don't skip it. 🙈

If there are two modules using FindBin from different directories under the same interpreter, this won't work. Periodt. Why? Because FindBin uses a BEGIN block, so it'll be executed only once, and only the first caller will get it right. 😭

This is a problem under mod_perl and other persistent Perl environments — where you shouldn't use this module at all. Which also means you should avoid using FindBin in modules that you plan to put on CPAN. Yeah. That's a real constraint, not a vibe check. 🫠

The fix? Call the again function to make sure that FindBin will work:

use FindBin;
FindBin::again(); # or FindBin->again;
⭐ Fun lore: in former versions of FindBin there was no again function. The workaround was to force the BEGIN block to be executed again:
delete $INC{'FindBin.pm'};
require FindBin;

Ancient technique. Works tho. 🧚

🍓 AUTHORS 🍓

FindBin is supported as part of the core perl distribution. 💜

Please submit bug reports at <https://github.com/Perl/perl5/issues> — the maintainers are literally waiting, be nice about it. 🫶

The actual legends behind it:

  • Graham Barr <gbarr@pobox.com>
  • Nick Ing-Simmons <nik@tiuk.ti.com>

Two icons. Respect. 👑

Copyright (c) 1995 Graham Barr & Nick Ing-Simmons. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🦋

And that's the page!! You now know more about FindBin than like 90% of people writing Perl, congrats babe 🌸

Signed off with love from perl v5.42.3, dated 2026-11-03 — the FindBin(3pm) girlies stay winning 💖✨

📦 where this page comes from