PAPERSWAY(1)

📦 version 3.000, in nixos 26.05, nixpkgs unstable

🌸 PAPERSWAY(1) — the manual, but make it make sense 🌸

okay bestie, so this is papersway(1), from the User Contributed Perl Documentation corner of the universe, and I'm gonna walk you through it like we're on FaceTime at 2am. no cap, it's actually lowkey iconic. 💅

✨ NAME ✨

papersway — PaperWM-like scrollable tiling window management for Sway/i3wm. that's the whole vibe. 🦋

💖 VERSION 💖

version 3.000. yes, three-point-zero-zero-zero, she's official.

🎀 SYNOPSIS 🎀

papersway [--i3status] [--cols=N|--cols-min-width=N] [--with-ws-cmd]
[--debug]

literally that's it. that's the whole invocation. she's not complicated, she's just ✨particular✨.

🌈 DESCRIPTION 🌈

okay so. this is an implementation of PaperWM-like scrollable tiling window management for Sway/i3wm. 🫶

here's the tea: if you love Sway/i3wm's whole commitment to stability, avoiding scope creep, etc. etc. — like, the values, the principle — but you cannot deal with the actual window management model? that's exactly who papersway is for. it's the alternative. main character energy for your windows. 👑

💅 OPTIONS 💅

  • --i3status — starts a background instance of i3status, then filters and prints its output. basically it handles the status bar thing for you. 🍓
  • --cols=N — sets the number of columns on a new workspace. the default, which is also the minimum, is 2. incompatible with --cols-min-width — pick a lane, bestie. 🙈
  • --cols-min-width=N — sets the number of columns on a new workspace to be the maximum that will fit while maintaining a column width of at least N pixels (with Sway, implicitly scaled by the output's scale factor). also incompatible with --cols. 🎀
  • --with-ws-cmd — don't hide the workspace buttons, and when you're using --i3status, don't include information about workspaces in the status output. 🦋
  • --debug — enables some debug printing, and doesn't hide Sway's workspace buttons. for when you need to see what's going on in there. 🔥

⭐ USAGE ⭐

so here's where we talk about integrating papersway into your existing Sway/i3wm configuration file. you'll usually find it at ~/.config/sway/config or ~/.config/i3/config, as appropriate. iykyk. 💜

🌸 Activation 🌸

the recommended way to activate papersway is by using it as your bar command. 👑

for Sway:

bar {
    status_command papersway --i3status

    # [ .. further bar options .. ]
}

and for i3:

bar {
    status_command papersway --i3status --with-ws-cmd
    workspace_command papersway-ws-cmd

    # [ .. further bar options .. ]
}

this ensures you can see a visual representation of your paper workspaces, which — ngl — is gonna be so useful while you're getting the hang of papersway. 🫶

🦋 Binding keys 🦋

here are some sample bindings to get you started. copy-paste responsibly, bestie:

set $mod Mod4

bindsym $mod+Left exec papersway-msg focus left
bindsym $mod+Down focus down
bindsym $mod+Up focus up
bindsym $mod+Right exec papersway-msg focus right

bindsym $mod+Shift+Left exec papersway-msg move left
bindsym $mod+Shift+Down move down
bindsym $mod+Shift+Up move up
bindsym $mod+Shift+Right move exec papersway-msg move right

bindsym $mod+f exec papersway-msg width toggle
bindsym $mod+o exec papersway-msg other-column

bindsym $mod+a exec papersway-msg fresh-workspace
bindsym $mod+n exec papersway-msg fresh-workspace send
bindsym $mod+t exec papersway-msg fresh-workspace take
bindsym $mod+b exec papersway-msg bury-workspace
bindsym $mod+Shift+b exec papersway-msg bury-column

bindsym $mod+e exec papersway-msg absorb-expel left
bindsym $mod+r exec papersway-msg absorb-expel right

bindsym $mod+minus exec papersway-msg cols decr
bindsym $mod+equal exec papersway-msg cols incr

bindsym $mod+u exec papersway-msg workspace prev_on_output
bindsym $mod+i exec papersway-msg workspace next_on_output
bindsym $mod+Shift+u exec papersway-msg move-to-workspace prev_on_output
bindsym $mod+Shift+i exec papersway-msg move-to-workspace next_on_output

bindsym $mod+c [con_mark=caffeinated] inhibit_idle none; \
    inhibit_idle open, mark caffeinated
bindsym $mod+Shift+c [con_mark=caffeinated] inhibit_idle none, \
    mark --toggle caffeinated
for_window [con_mark=caffeinated] inhibit_idle open
⚠️ okay important: delete any bindings you have for the split, splith, splitv, splitt, layout, focus parent and focus child commands, to avoid confusion — on the parts of both yourself and of papersway. yes, both. you're a team now. 😭

💀 Other configuration 💀

  • set focus_wrapping to no. 🚫
  • set default_orientation to horizontal. ➡️
  • leave workspace_layout with its default value, default. don't touch her, she's fine. 🙈

👀 SEE ALSO 👀

<https://github.com/paperwm/PaperWM>, i3status(1), sway(5)

go read them, they're literally right there. 🧚

🫶 AUTHOR 🫶

Sean Whitton <spwhitton@spwhitton.name>

this software is Copyright (c) 2019-2026 by Sean Whitton <spwhitton@spwhitton.name>.

this is free software, licensed under:

The GNU General Public License, Version 3, June 2007

and that's the whole page, bestie 🎀✨ this was perl v5.42.3, dated 2026-04-25, PAPERSWAY(1) — now go forth and scroll your windows like the icon you are 💖💅🦋

📦 where this page comes from