PLACKUP(1)

💖 PLACKUP 💖

okay bestie, welcome to the plackup page — it's the user-contributed Perl doc for the lil command that runs your PSGI app from the terminal. it's giving "server-wrangler energy" and honestly? iconic. let's go 🫶

---

✨ NAME ✨

plackup — run a PSGI application with Plack handlers 💅

---

🌸 SYNOPSIS 🌸

# read your app from app.psgi file
plackup

# choose .psgi file from ARGV[0] (or with -a option)
plackup hello.psgi

# switch server implementation with --server (or -s)
plackup --server HTTP::Server::Simple --port 9090 --host 127.0.0.1 test.psgi

# use UNIX socket to run FCGI daemon
plackup -s FCGI --listen /tmp/fcgi.sock myapp.psgi

# launch FCGI external server on port 9090
plackup -s FCGI --port 9090

---

🦋 DESCRIPTION 🦋

so plackup is a command line utility whose whole job is running PSGI applications straight from the terminal. that's it. that's the gig. 👑

it's lowkey a genius — plackup automatically figures out the environment it's running in and then runs your app in that environment. like, it just knows. FastCGI, CGI, AnyEvent and others can all be detected. if you want the authoritative list, go check Plack::Loader — that's the source of truth fr fr.

k so here's the vibe: plackup assumes you've got an app.psgi script chillin' in your current directory. and the last statement of app.psgi needs to be a code reference that is a PSGI application. like this:

#!/usr/bin/perl
use MyApp;
my $application = MyApp->new;
my $app = sub { $application->run_psgi(@_) };

that last line? she's the main character. don't forget her. 🌟

---

🎀 ARGUMENTS 🎀

• .psgi

plackup --host 127.0.0.1 --port 9090 /path/to/app.psgi

the first non-option argument gets used as your .psgi file path. you can also set this path with -a or --app, bestie, whichever vibe you prefer. and if you just... don't say anything? no path at all? the default file path is app.psgi in the current directory. she's always there for you. 💖

---

💅 OPTIONS 💅

• -a, --app — tells plackup the full path to your .psgi script. you can alternately hand this path over as the first argument to plackup instead. your call, no wrong answers. ✨
• -e — evaluates the given perl code as a PSGI app, basically exactly like perl's own -e option:

plackup -e 'sub { my $env = shift; return [ ... ] }'

it's also super handy when you wanna run a custom application like Plack::App::*:

plackup -MPlack::App::File -e 'Plack::App::File->new(...)->to_app'

you can also use -e together with a .psgi file path to wrap the application with middleware configuration straight from the command line. you can even use Plack::Builder DSL syntax inside the -e code. for example:

plackup -e 'enable "Auth::Basic", authenticator => ...;' myapp.psgi

is equivalent to this PSGI application:

use Plack::Builder;
use Plack::Util;

builder {
    enable "Auth::Basic", authenticator => ...;
    Plack::Util::load_psgi("myapp.psgi");
};

heads up bestie!! when you use the -e option to enable middleware, plackup does not assume the implicit app.psgi path. you must either pass the path to your .psgi file in the command line arguments, or load the application inside -e after the enable. no cap. 👇

plackup                                # Runs app.psgi
plackup -e 'enable "Foo"'              # Doesn't work!
plackup -e 'enable "Foo"' app.psgi     # Works
plackup -e 'enable "Foo"; sub { ... }' # Works

• -o, --host — binds to a TCP interface. defaults to undef, which lets most server backends bind to the any (*) interface. this option is only valid for servers that support TCP sockets. 🧚
• -p, --port — binds to a TCP port. defaults to 5000. this option is only valid for servers that support TCP sockets.

note: the default port 5000 may conflict with the AirPlay server on MacOS 12 (Monterey) or later. so if something's acting weird on your Mac... it's probably that. 😭

• -s, --server, and the PLACK_SERVER environment variable — picks a specific server implementation to run on. when provided, the -s or --server flag is preferred over the environment variable. 💯

if no option is given at all, plackup will try to detect the best server implementation based on the environment variables as well as modules loaded by your application in %INC. see Plack::Loader for details.

• -S, --socket — listens on a UNIX domain socket path. defaults to undef. this option is only valid for servers that support UNIX sockets. 🔥
• -l, --listen — listens on one or more addresses, whether it's HOST:PORT, :PORT, or PATH (no colons). you may use this option multiple times to listen on multiple addresses — but heads up, the server itself decides whether it supports multiple interfaces. not us. the server. 👑
• -D, --daemonize — makes the process run in the background. whether this option is respected or not is entirely up to the backend server/handler implementation. so like... it might just ignore you. 🙈
• -I — specifies Perl library include paths, just like perl's own -I option. you may add multiple paths by using this option multiple times.
• -M — loads the named modules before loading the app's code. you may load multiple modules by using this option multiple times.

careful!! in combination with -r or -R, this may not have the desired restart effect when the loaded module is changed in the development directory. to avoid this problem you need to load the module with the app code using -e.

• -E, --env, and the PLACK_ENV environment variable — specifies the environment option. setting this value with -E or --env also writes to the PLACK_ENV environment variable, which lets applications or frameworks know which environment setting the application is running on. 🫶

# These two are the same
plackup -E deployment
env PLACK_ENV=deployment plackup

common values are development, deployment, and test. the default value is development, which causes plackup to load the middleware components: AccessLog, StackTrace, and Lint — unless --no-default-middleware is set. 🌈

• --no-default-middleware — this prevents loading the default middleware stack even when the Plack environment (i.e. -E or PLACK_ENV) is set to development. you're the boss. 🎀
• -r, --reload — makes plackup restart the server whenever a file in your development directory changes. this option by default watches the lib directory and the base directory where the .psgi file is located. use -R to watch other directories. 👀

reloading will delay the compilation of your application. automatic server detection (see -s above) may not behave how you expect, if plackup needs to scan your application for the modules it uses. avoid problems by specifying -s explicitly when using -r or -R. -s said explicitly. ok periodt.

to avoid problems with changes to preloaded modules, see the documentation for -M.

• -R, --Reload — makes plackup restart the server whenever a file in any of the given directories changes. -R and --Reload take a comma-separated list of paths:

plackup -R /path/to/project/lib,/path/to/project/templates

to avoid problems with changes to preloaded modules, see the documentation for -M.

• -L, --loader — specifies the server loading subclass that implements how to run the server. available options are Plack::Loader (default), Restarter (automatically set when -r or -R is used), Delayed, and Shotgun. ⭐

see Plack::Loader::Delayed and Plack::Loader::Shotgun for more details.

• --access-log — specifies the pathname of a file where the access log should be written. by default, in the development environment, access logs will go to STDERR. 💜
• --path — specify the root path of your app (SCRIPT_NAME in the PSGI env) to run. the following two commands are roughly the same:

plackup --path /foo app.psgi
plackup -e 'mount "/foo" => Plack::Util::load_psgi("app.psgi")'

• other options that start with -- are passed through to the backend server. see each Plack::Handler backend's documentation for more details on their available options. pass it along bestie, we don't gatekeep. 🌟

---

🔥 SEE ALSO 🔥

Plack::Runner Plack::Loader

---

and that's the whole page, bestie!! 🥳 go forth and run your PSGI apps, you absolute icon. this was documented for perl v5.42.3, dated 2026-10-18, under User Contributed Perl Documentation — mwah, love u, bye 💖🎀🦋