Record Terminal Sessions and Generate GIF on Linux [Guide]

Terminal recordings are useful for documentation, tutorials, bug reports, and live demos. Instead of recording your entire screen with a heavy video tool, you can capture just the terminal session as a lightweight asciicast file and convert it to a GIF image. This guide covers two tools for recording Linux terminal sessions and generating GIF images – asciinema with agg, and terminalizer.

Original content from computingforgeeks.com - post 2974

We will walk through installing each tool, recording terminal sessions, playing them back, and converting recordings to GIF files. All commands are tested on Ubuntu 24.04 but work on most Linux distributions with minor package manager adjustments.

Prerequisites

A Linux system running Ubuntu 24.04, Debian 13, Rocky Linux 10, or Fedora 42
sudo or root access
Internet access to download packages and binaries
Node.js and npm (only required for terminalizer)

Part 1: Record Terminal Sessions with asciinema and agg (Recommended)

asciinema is a mature, well-maintained tool that records terminal sessions as text-based asciicast files. Combined with agg (asciinema gif generator), you get a clean workflow for producing GIF images from terminal recordings.

Step 1: Install asciinema

asciinema is available in the default repositories of most Linux distributions. Install it with your package manager.

On Ubuntu/Debian:

sudo apt update
sudo apt install -y asciinema

On Fedora:

sudo dnf install -y asciinema

On Arch Linux:

sudo pacman -S asciinema

Verify the installation by checking the version:

asciinema --version

The output confirms asciinema is installed and ready:

asciinema 2.4.0

Step 2: Record a Terminal Session

Start recording your terminal session to a .cast file. asciinema captures everything you type and all command output in the asciicast v2 format.

asciinema rec output.cast

This drops you into a new shell session where everything is recorded. Run your commands normally, then press Ctrl+D or type exit to stop the recording.

To record a specific command instead of an interactive session, use the -c flag:

asciinema rec output.cast -c 'ls -la /etc'

This records only the output of that single command and stops automatically when the command finishes.

The recording is stored in JSON-based asciicast v2 format. You can inspect the metadata header of the cast file:

head -1 output.cast

The first line contains recording metadata including terminal dimensions and shell information:

{"version": 2, "width": 80, "height": 24, "timestamp": 1774139808, "env": {"SHELL": "/bin/bash", "TERM": null}}

A typical short recording produces a small file – around 1.9K for a 17-line cast file.

Step 3: Play Back Recordings

Play back a recorded session directly in your terminal:

asciinema play output.cast

This replays the session in real time, exactly as it was recorded. You can press Space to pause/resume and Ctrl+C to quit.

To speed up playback, use the --speed flag. A value of 2 plays at double speed:

asciinema play output.cast --speed 2

This is helpful for reviewing long recordings quickly before converting them to GIF.

Step 4: Share Recordings on asciinema.org

asciinema has a built-in sharing feature that uploads your recording to asciinema.org, where anyone can view it in a web player.

asciinema upload output.cast

After uploading, asciinema returns a URL where the recording can be viewed and embedded. This is useful for sharing in documentation, GitHub issues, or blog posts without needing to generate a GIF file.

Step 5: Generate GIF Images with agg

agg (asciinema gif generator) converts .cast files into GIF images. It is a standalone binary – download the latest release from GitHub.

Download and install agg v1.7.0:

wget https://github.com/asciinema/agg/releases/download/v1.7.0/agg-x86_64-unknown-linux-gnu
chmod +x agg-x86_64-unknown-linux-gnu
sudo mv agg-x86_64-unknown-linux-gnu /usr/local/bin/agg

Verify the installation:

agg --version

You should see the version number confirming agg is ready:

agg 1.7.0

Convert a cast file to GIF with default settings:

agg output.cast output.gif

This generates a GIF file – a short recording produces a file around 33K with the default theme.

For more control over the output, use agg’s options to set terminal dimensions, font size, and color theme:

agg output.cast output.gif --cols 100 --rows 30 --font-size 14

agg supports several built-in color themes. Apply a theme with the --theme flag:

agg output.cast output-dracula.gif --theme dracula

The available themes are:

asciinema – default theme matching asciinema.org player colors
dracula – dark theme with vibrant colors
monokai – dark theme popular among developers
solarized-dark – Ethan Schoonover’s dark Solarized palette
solarized-light – light variant of the Solarized palette

Using the dracula theme produces a slightly larger file – around 40K compared to 33K with the default theme – due to the richer color palette.

Here is a summary of useful agg options:

Option	Description
`--cols`	Set terminal width in columns (overrides recording value)
`--rows`	Set terminal height in rows (overrides recording value)
`--font-size`	Font size in pixels (default: 14)
`--theme`	Color theme (asciinema, dracula, monokai, solarized-dark, solarized-light)
`--speed`	Playback speed multiplier
`--fps-cap`	Maximum frames per second for the GIF

Part 2: Record Terminal Sessions with Terminalizer (Alternative)

Terminalizer is a Node.js-based terminal recording tool. It records sessions in its own YAML-based format and can render GIF images directly. It works well if you already have Node.js in your environment, though it has more dependencies than asciinema.

Step 6: Install Terminalizer

Terminalizer requires Node.js and npm. Install it globally with npm:

npm install -g terminalizer

Verify the installation:

terminalizer --version

The version confirms terminalizer is installed:

0.12.0

Step 7: Record and Render GIF with Terminalizer

Start recording a terminal session with terminalizer. The recording is saved as a YAML file:

terminalizer record demo

Run your commands in the recorded session, then press Ctrl+D to stop. The recording is saved as demo.yml.

Play back the recording in the terminal:

terminalizer play demo

This replays the session just like asciinema play, showing the recorded commands and output in real time.

Render the recording as a GIF image:

terminalizer render demo

This generates a GIF file from the recording. The rendering process uses Electron under the hood, so it may take a moment depending on the recording length.

Terminalizer stores its configuration in a YAML config file. View the default config location:

terminalizer config

This outputs the path to the global config file where you can adjust default recording settings like frame delay, cursor style, terminal font, and GIF quality.

asciinema vs Terminalizer Comparison

Both tools get the job done, but they differ in approach and dependencies. Here is a side-by-side comparison:

Feature	asciinema + agg	Terminalizer
Install method	System package manager + single binary	npm (requires Node.js)
Recording format	asciicast v2 (JSON-based)	YAML
GIF generation	agg (separate Rust binary, fast)	Built-in (uses Electron, slower)
Sharing	asciinema.org web player	terminalizer.com (limited)
Dependencies	Minimal (Python for asciinema, none for agg)	Node.js, npm, Electron
Theme support	5 built-in themes in agg	Configurable via YAML
Playback speed control	Yes (–speed flag)	Yes (config file)
Active development	Yes – actively maintained	Less active

For most use cases, asciinema with agg is the better choice. It has fewer dependencies, produces smaller output files, runs faster, and is actively maintained. Terminalizer is a reasonable alternative if you prefer a single tool that handles recording and GIF generation without a separate converter.

Conclusion

You now have two working methods for recording Linux terminal sessions and generating GIF images. asciinema paired with agg gives you a lightweight, fast pipeline with multiple theme options and the ability to share recordings via asciinema.org. Terminalizer provides an all-in-one solution at the cost of heavier Node.js dependencies.

For production documentation workflows, keep your cast files in version control alongside your docs. This lets you re-render GIFs with different themes or dimensions anytime without re-recording the session.