Execute commands and long-running scripts in the background using screen

There’s an easy way to keep scripts and commands “alive” when you disconnect from a server.

screen lets you pick up things right where you left them

The command line lets you run commands and programs. Some commands, like cd or ls, are fast. Others, like mysqldump, scp, or sudo apt install, may take a while to complete. You often want to monitor the progress of such long-running commands.

It’s usually not very hard to keep an eye on what’s happening: just wait until the command finishes. But sometimes this isn’t possible, for instance when you’re about to turn off your computer or have a really bad internet connection. Once you disconnect from the server the command either stops executing or keeps running invisibly in the background, with no easy way to “go back”.

Follow the three steps below to use screen:

1. Begin a new session
2. Temporarily detach from the session
3. Resume your session later

Start

Let’s say you want to run a command that will take a long time to complete. You want to keep an eye on it, but you don’t have time to wait for it right now. If you want to run this command using screen, you first need to start a new session.

Technically this can be done by simply issuing the screen command, but don’t do this! By default screen generates session names that may be hard to remember, like 2041652.pts-3.vs-cza-d41d48.

Instead, give your session a nice name, so that you (or others who have access to the same machine) can easily recognise it:

screen -S $NAME

Replace $NAME with whatever you want. Ideally, pick a simple name that describes why you started the session or that mentions your name. Try to avoid spaces and special characters (other than - and .), as these can make it harder to return to the session later.

For example, to start a session named upgrade-database, execute the following command:

screen -S upgrade-database

Stop

At some point (usually directly after executing a long-running command), you’ll want to leave your session. There are two ways to do this.

It may help to think of sessions as application windows. As long as you keep a window open, everything in that window continues to work as normal.

When you’re temporarily done with a window, you can minimise it. In screen terminology this is called detaching. To detach from a session, press Ctrl + A, followed by Ctrl + D. If you’re using a terminal emulator like Windows Terminal or iTerm2, you can also simply close the tab to detach from the session.

Alternatively, once the command has finished and you no longer need the session, you can completely end it by pressing Ctrl + D. This is more akin to closing a window: if you do this, the session is gone and you can’t return to it.

Continue

When you detach from a session it’s still active in the background. Use screen -r to reattach to an existing session:

screen -r $SESSION_NAME

$SESSION_NAME is the name that you previously entered when you started the session via screen -S. For example:

screen -r upgrade-database

If you forgot the name of your session, you can use screen -ls to see a list of sessions that are still active:

$ screen -ls
There is a screen on:
  54757.upgrade-database  (04/10/23 18:11:31)   (Detached)
  54675.derp              (04/10/23 18:09:52)   (Detached)
  17853.derp              (04/05/23 15:22:05)   (Detached)
3 Socket in /run/screen/S-foobar

screen -r 54675

But wait, there’s more

In practice you’ll rarely encounter situations where you need something other than the three steps I showed above. But you want to learn more about screen, you can always use screen --help to display all the available options:

-a            Force all capabilities into each window's termcap.
-A -[r|R]     Adapt all windows to the new display width & height.
-c file       Read configuration file instead of '.screenrc'.
-d (-r)       Detach the elsewhere running screen (and reattach here).
-dmS name     Start as daemon: Screen session in detached mode.
-D (-r)       Detach and logout remote (and reattach here).
-D -RR        Do whatever is needed to get a screen session.
-e xy         Change command characters.
-f            Flow control on, -fn = off, -fa = auto.
-h lines      Set the size of the scrollback history buffer.
-i            Interrupt output sooner when flow control is on.
-list         or -ls. Do nothing, just list our SockDir.
-L            Turn on output logging.
-m            ignore $STY variable, do create a new screen session.
-O            Choose optimal output rather than exact vt100 emulation.
-p window     Preselect the named window if it exists.
-q            Quiet startup. Exits with non-zero return code if unsuccessful.
-r            Reattach to a detached screen process.
-R            Reattach if possible, otherwise start a new session.
-s shell      Shell to execute rather than $SHELL.
-S sockname   Name this session <pid>.sockname instead of <pid>.<tty>.<host>.
-t title      Set title. (window's name).
-T term       Use term as $TERM for windows, rather than "screen".
-U            Tell screen to use UTF-8 encoding.
-v            Print "Screen version 4.00.03 (FAU) 23-Oct-06".
-wipe         Do nothing, just clean up SockDir.
-x            Attach to a not detached screen. (Multi display mode).
-X            Execute <cmd> as a screen command in the specified session.