PAPERSWAY(1p)

📦
version 3.000 · 3 versions
, in ubuntu stonking

💖 papersway — like, the manual but make it make sense 💖

okay so bestie, welcome to papersway(1p), from the User Contributed Perl Documentation corner of the universe. Grab a strawberry 🍓, sit down, and let me tell you about the scrollable tiling window management that's about to rearrange your entire life. No cap.

✨ NAME ✨

papersway — PaperWM-like scrollable tiling window management for Sway/i3wm 🦋

🌸 VERSION 🌸

version 3.000

🎀 SYNOPSIS 🎀

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

💅 DESCRIPTION 💅

So here's the vibe. This is an implementation of PaperWM-like scrollable tiling window management for Sway/i3wm. Like, if you're obsessed with how Sway/i3wm keeps it stable and refuses to let the scope creep in — iconic behaviour honestly 👑 — but the window management model itself is giving you the ick? Yeah. papersway is your alternative. It's the main character energy your window manager was missing.

🔥 OPTIONS 🔥

  • --i3status — spins up a background instance of i3status, then filters its output and prints it for you. It's the little helper that could. ✨
  • --cols=N — sets how many columns you get on a brand-new workspace. The default, and also the minimum, is 2. Incompatible with --cols-min-width, just so we're clear. Don't do both. 💀
  • --cols-min-width=N — sets the number of columns on a new workspace to the maximum that'll actually fit while keeping a column width of at least N pixels (and with Sway, that's implicitly scaled by the output's scale factor, iykyk). Incompatible with --cols. Pick one, bestie 🙈
  • --with-ws-cmd — keeps your workspace buttons visible instead of hiding them, and when you're using --i3status, it leaves info about workspaces out of the status output. Very demure.
  • --debug — turns on a lil bit of debug printing, and does not hide Sway's workspace buttons. For when you need to see everything.

🌈 USAGE 🌈

Okay so this is the part where we talk about how to actually, like, integrate papersway into your existing Sway/i3wm config file. You'll usually find that at ~/.config/sway/config or ~/.config/i3/config, whichever one is yours. 🫶

⭐ Activation ⭐

The recommended way to activate papersway is to use it as your bar command. It's giving "just let it be the bar, trust me."

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 .. ]
}

The whole point of doing it this way is that you get a visual representation of your paper workspaces, which is genuinely gonna be so useful while you're getting the hang of how papersway works. Periodt.

💜 Binding keys 💜

Here are some sample bindings to get you started, babe. Copy these into your config and slay.

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
🚨 bestie listen to me: delete any bindings you have for the split, splith, splitv, splitt, layout, focus parent and focus child commands. Just yeet them. Otherwise it's confusion city — for you AND for papersway. Nobody wants that. 😭

🧚 Other configuration 🧚

  • Set focus_wrapping to no.
  • Set default_orientation to horizontal.
  • Leave workspace_layout at its default value, default. Don't touch it. Let it be. 🌸

🦋 SEE ALSO 🦋

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

👑 AUTHOR 👑

Sean Whitton <spwhitton@spwhitton.name> — king behaviour, fr fr 💖

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

aaaand that's the whole page, bestie! 🎀 Mwah. This was built against perl v5.40.1, dated 2026-04-25, and if you ever needed to cite it you'd do it as PAPERSWAY(1p). Go forth and tile your windows horizontally. Slay. 💅✨

📦 where this page comes from