FindBin(3perl)

💖 FindBin — the manual page, but make it a group chat 💖

okay bestie, so this is FindBin, a little module from the Perl Programmers Reference Guide section 3, and it is genuinely one of the most useful little gremlins in the whole core distribution. sit down, grab a strawberry 🍓, let's go.

---

✨ NAME ✨

FindBin — literally just: locate the directory of the original Perl script. that's it. that's the whole job. and it ATE. 💅

---

🌸 SYNOPSIS 🌸

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

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

see how clean that is?? iconic. no cap.

---

🦋 DESCRIPTION 🦋

so what it does is: it finds the full path to the script's bin directory, so you can use paths that are relative to that bin directory. that's the entire vibe. 🎀

which means you can set up a cute little directory tree for your software with a <root>/bin directory and a <root>/lib directory, and then the example above just works — you can use modules from the lib directory without ever needing to know where the software tree actually got installed on the machine. main character energy fr fr. ✨

and if perl gets invoked with the -e option, or your Perl script is being read from STDIN? then FindBin sets both $Bin and $RealBin to the current directory. not the script's directory. the current one. noted. 💀

---

👑 EXPORTABLE VARIABLES 👑

here's the lineup, bestie. memorize it, it's like three seconds of your life:

• $Bin or $Dir — the 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, but with all the links resolved 🌈
• $RealScript — $Script, but with all the links resolved

and if you want all of them at once (greedy, love that for you), there's the ALL tag:

use FindBin ':ALL';

periodt. 💖

---

😭 KNOWN ISSUES 😭

okay. this is the part where we get real. 🫠

if there are two modules using FindBin from different directories under the same interpreter, this won't work. and the reason is so petty: FindBin uses a BEGIN block, so it only gets executed once, and only the first caller gets it right. everyone after that is just out here living a lie. 💀

this is a genuine problem under mod_perl and other persistent Perl environments — and in those environments 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. i'm so serious. 🙈

the fix: call the again function to make sure FindBin actually works:

use FindBin;
FindBin::again(); # or FindBin->again;

and in former versions of FindBin there was no again function (chaotic era, honestly), so the workaround was to force the BEGIN block to be executed again:

delete $INC{'FindBin.pm'};
require FindBin;

look at her. vintage. 🎀

---

🫶 AUTHORS 🫶

FindBin is supported as part of the core perl distribution. if you find a bug, please submit bug reports at:

<https://github.com/Perl/perl5/issues>

and shoutout to the actual legends:

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

we stan. 👑

---

⭐ COPYRIGHT ⭐

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. slay, legally speaking. 💅

---

okay that's the whole page, bestie, you're officially literate in FindBin now. go forth and find your bin. 🦋🌸💖

and for the record: this was perl v5.44.0, dated 2026-10-17, from FindBin(3perl). iykyk ✨