rxvt-unicode - ArchWiki

Jump to content
Toggle the table of contents

# rxvt-unicode

4 languages

- Deutsch
- 日本語
- Русский
- 中文（简体）

From ArchWiki

Related articles

- rxvt-unicode/Tips and tricks

rxvt-unicode (urxvt) is a customizable terminal emulator forked from rxvt, with support for Perl extensions.

## Installation

Install one of the following:

- rxvt-unicode,
- rxvt-unicode-truecolor-wide-glyphsAUR — improved font rendering, enhanced glyph support, applied True color support,

or search AUR for opinionated builds with different patches and configuration options applied.

Patches
File name | Description
--- | ---
`7-bit-queries.patch` | multiple-char sequence for 7-bit queries — is needed for correct work of color OSC commands; merged upstream
`24-bit-color.patch` | True Color support
`256color.patch` | 256 ~/.Xresources colors
`background-opacity.patch` | fixed opacity (pixbuf-related)
`clear.patch` | Control-L keeps all lines from the screen in the scrollback buffer (VTE-like behavior)
`enable-wide-glyphs.patch` | enhancing glyph support, required by `improve-font-rendering.patch`
`font-width-fix.patch` | decreasing space between symbols, incompatible with (replaced by) `improve-font-rendering.patch`
`improve-font-rendering.patch` | font rendering improvements
`line-spacing-fix.patch` | vertical spacing improvement, incompatible with (replaced by) `improve-font-rendering.patch`
`lines-rewrap.patch` | solves the #Wrong shell prompt placement after upgrade to 9.31 problem
`matcher-vi-bindings.patch` | add vi-style (hjkl) keys to matcher extension to mimic deprecated ulr-select behavior
`noinc.diff` | no increment resizing — is needed for better Openbox user experience
`perl-5.38.patch` | locale fix required by Perl 5.38; merged upstream
`popup-menu-hang.diff` | fixing popup Perl extension hanging
`rxvt-unicode-sixel.patch` | DEC Sixel support expressing character bitmap image via DEC Device Control String (DCS) Sixel `P…q` escape sequence like "`ESC` `Pq` `...` `ESC\`"
`rxvt-unicode-truecolor.patch` | the same as `24-bit-color.patch`
`secondaryWheel.patch` | scrolling in the secondary screen with the mouse wheel
`starttop.patch` | commenting out line 397 of `screen.C` — one of the approaches to the #Wrong shell prompt placement after upgrade to 9.31 problem

3rd party Perl Extensions
File name, link | Package | Description
--- | --- | ---
keyboard-select |  | use keyboard shortcuts to select and copy text
resize-font | urxvt-resize-font-gitAUR | use keyboard shortcuts to adjust the font size; fractional intervals (like `0.5`) also supported

## Configuration

### X resources

Rxvt-unicode is controlled by command-line arguments or X resources. Command-line arguments override, and take precedence over resource settings.

The first component of a resource is either the class (`URxvt`) or an application (instance) name. Application name can be specified with urxvt(1) § name command-line option and is set to `urxvt` — a binary basename(1) — by default. For a given instance, resources defined with an application name override, and take precedence over defined with the class name ones.

Note: Rxvt-unicode resource naming scheme does not heavily utilize nested components as xterm does. Valid sample of loose binding (asterisk, `*`) usage is provided in the urxvt(7) § Terminal Configuration section.

See urxvt(1) and urxvt(7) for available settings, resources and values. Also `urxvt --help` prints all available resources to the standard error. Each resource can be used as a long command-line option.

Use xrdb(1) (xorg-xrdb) to apply the configuration like so: `xrdb ~/.Xresources`. Depending on your environment you may have to use `-merge` option. The new configuration is applied to only new instances, not the existing ones.

### Fonts

Rxvt-unicode does not utilize fontconfig library for font substitution when a font or individual character is not present. I.e. you must provide all font names in the corresponding resources (set the fontsets) for all glyphs you are interested in.

Ability to use non-monospaced fonts (like `Nerd Font` vs. `Nerd Font Mono`) hardly depends on your environment (see #Spacing) and the font itself.

If a glyph can't be displayed or can't be found it is substituted with an empty square.

Rxvt-unicode supports both X FreeType (Xft) and X Logical Font Description (XLFD), urclock(1) supports XLFD only.

#### Permanent

    ~/.Xresources

    URxvt.font:           xft:Input Mono:size=13:style=Regular,\
                          xft:Font Awesome 6 Free:style=Solid
    URxvt.boldFont:       xft:Input Mono:size=13:style=Medium
    URxvt.italicFont:     xft:Input Mono:size=13:style=Italic
    URxvt.boldItalicFont: xft:Input Mono:size=13:style=Medium Italic

Note: If there is a hyphen (`-`) in an Xft font name, it must be escaped with backslash (`\`) twice. It is different from the usage of `urxvt -fn` option and the result that fc-list returns, where backslash present only once.

#### Non-permanent

You can change the fonts of the current instance with Xterm Operating System Commands (OSC). Use numeric (Ps) parameters 710–713 followed by corresponding text (Pt) parameter, like so (also see urxvt(1) § CHANGING FONTS):

    $ printf '\x1b\x5d710;%s\x1b\x5c' "xft:Terminus:pixelsize=22"
    $ printf      '\e]711;%s\a'       "xft:Terminus:pixelsize=22:bold"

To change font size of the current instance with keyboard shortcuts use `resize-font` Perl extension.

#### Spacing

You may need to tweak the horizontal distance between characters with `letterSpace` and/or the vertical distance between rows with urxvt(1) § lineSpace:. These needs depend on:

- using rendering improvement patches, like enable-wide-glyphs.patch, improve-font-rendering.patch, font-width-fix.patch or line-spacing-fix.patch,
- using languages with glyphs that are too different from English letters, like Arabian, Chinese, Hebrew, Japanese or Korean,
- your font and its size.

### Scrollback buffer

Tip: The mouse wheel scrolls five lines by default, and one line while Shift is pressed. If you want to change these numbers — you have to edit the source code.

#### Behavior on receiving new output

By default, when shell output appears, the scrollback view will automatically jump to the bottom of the buffer to display new output.

If you want to see previous output (e.g., compiler messages) while pseudo-TTY is still receiving new lines, and jump to the bottom of the scrollback buffer on key press, use the following options:

    URxvt.scrollTtyOutput:   False
    URxvt.scrollWithBuffer:  True
    URxvt.scrollTtyKeypress: True

#### Secondary screen

When you scroll a pager in a secondary screen (e.g. using less(1) without the `-X/--no-init` option), it may be a good idea to disable secondary screen scroll to be able to scroll in the pager itself, instead of the terminal's buffer.

This is default and unchangeable behavior in Konsole and VTE-based terminal emulators. To achieve the same behavior in urxvt, use the following:

    URxvt.secondaryScroll: False

The above configuration works as expected, except when scrolling with a mouse wheel. When you scroll a pager in the secondary screen with the mouse wheel, and there has been something in the scrollback buffer — the scrollback buffer will be scrolled by the mouse wheel, instead of the pager itself.

To solve this issue, it is necessary to introduce a new option into urxvt. Use packages like rxvt-unicode-better-wheel-scrolling-unicode3AUR or rxvt-unicode-fontspacing-noinc-vteclear-secondarywheelAUR , or apply `secondaryWheel.patch`. After installing, set the following:

    URxvt.secondaryWheel: True

Note: Avoid using this option with the urxvt-vtwheelAUR perl extension, as it will conflict.

#### Clearance

Reset to Initial State (RIS) `ESC 06/03` control function empties the screen and the scrollback buffer. You can bind it to your desired keys like so:

    URxvt.keysym.Meta-Control-l: command:\033c

#### Keeping the screen content on screen clearance

In urxvt pressing Control-L empties the screen, and the screen content is thrown away — you can't see it in the scrollback buffer later. This behavior might seems controversial for users with Konsole or VTE-based terminal emulators experience, where Control-L keeps the screen content in the scrollback buffer.

To achieve such VTE-like behavior in urxvt you can use appropriate package like rxvt-unicode-better-wheel-scrolling-unicode3AUR or rxvt-unicode-fontspacing-noinc-vteclear-secondarywheelAUR, or apply `clear.patch` in your preferred build.

#### Scrollbar

Scrollbar look and feel is controlled by a dozen of resources. Look at the manual around urxvt(1) § scrollstyle: and urxvt(1) § scrollColor: resources, and see urxvt(1) § THE SCROLLBAR section.

You can also change visibility of scrollbar on the fly for the current instance with DEC Private Modes urxvt(7) § Escape Sequences (`Pm = 30`). For example, you can bind scrollbar visibility toggling to a keyboard shortcut:

    URxvt.keysym.Meta-Control-s: command:\033[?30t

#### Saving to a file

Ctrl-Print or Shift-Print saves the scrollback buffer content to a file with a setting like so:

    URxvt.print-pipe: cat > ~/Downloads/URxvt_$(date '+%Y-%m-%d_%H:%M:%S').txt

- Print is usually the Print Screen key.
- Print alone saves the screen without the scrollback buffer.

### Clipboard

Rxvt-unicode clipboard behavior might seem controversy for people without xterm background. See urxvt(1) § THE SELECTION: SELECTING AND PASTING TEXT for details.

You can use urxvt-eval(1) with key bindings to setup copying to and pasting from CLIPBOARD:

    URxvt.keysym.Control-Insert:    eval:selection_to_clipboard
    URxvt.keysym.Shift-Insert:      eval:paste_clipboard

urxvt-selection-to-clipboard(1) can be used to synchronize CLIPBOARD with PRIMARY selection.

The urxvt-confirm-paste(1) extension displays a confirmation dialog when a paste containing control characters (like newlines) is detected. It is part of the `default` set and is loaded automatically, see urxvt(1) § perl-ext-common and #Disabling Perl extensions for more info.

## Perl extensions

We can enable Perl extensions by including the following line:

    URxvt.perl-ext-common: extension_name_1,extension_name_2,...

Note: There should not be any spacing between extension names.

See also:

- urxvt(1) § perl-ext-common — the resource description
- urxvt-extensions(1) — list of available (prepackaged) extensions, don't confuse with `default` extension set
- `$ man 1 urxvt-extension_name` — manual pages for specific prepackaged extensions
- urxvtperl(3) — embedded Perl interpreter manual

### Clickable URLs

You can make URLs in the terminal clickable using the matcher extension. For example, to open links in the default web browser with the left mouse button, add the following to `.Xresources`:

    URxvt.perl-ext-common: default,matcher
    URxvt.url-launcher: /usr/bin/xdg-open
    URxvt.matcher.button: 1

Since rxvt-unicode 9.14, it is also possible to use matcher to open and list recent (currently limited to 10) URLs via keyboard:

This article or section is out of date.

Reason: `perl:STRING *DEPRECATED*`, see urxvt(1) § perl:STRING. (Discuss in Talk:Rxvt-unicode)

    URxvt.keysym.C-Delete: perl:matcher:last
    URxvt.keysym.M-Delete: perl:matcher:list

Matching links can be colored with a chosen foreground or background color, for example blue:

    URxvt.matcher.rend.0: Uline Bold fg5

Alternatively, use `colorUL` for a #RRGGBB color. This will however color all underlined text, instead of only link matches:

    URxvt.colorUL: #4682B4

### Simple tabs

To add tabs to urxvt, add the following to your `~/.Xresources`:

    URxvt.perl-ext-common: ...,tabbed,...

To control tabs use:

Key | Description
--- | ---
`Shift+Down` | New tab
`Shift+Left` | Go to left tab
`Shift+Right` | Go to right tab
`Ctrl+Left` | Move tab to the left
`Ctrl+Right` | Move tab to the right
`Ctrl+d` | Close tab

You can change the colors of tabs with the following:

    URxvt.tabbed.tabbar-fg: 2
    URxvt.tabbed.tabbar-bg: 0
    URxvt.tabbed.tab-fg: 3
    URxvt.tabbed.tab-bg: 0

In order to make the tabbar transparent set its value to -1

    URxvt.tabbed.tabbar-bg: -1

If you need to rename the tab, you would probably want to install urxvt-tabbedexAUR instead.

### Fullscreen

You can install the AUR package urxvt-fullscreenAUR, and then set a key binding to put urxvt fullscreen.

This article or section is out of date.

Reason: `perl:STRING *DEPRECATED*`, see urxvt(1) § perl:STRING. (Discuss in Talk:Rxvt-unicode)

    URxvt.perl-ext-common:  ...,fullscreen,...
    URxvt.keysym.F11:       perl:fullscreen:switch

### Disabling Perl extensions

If you do not use the Perl extension features, you can improve the security and speed by disabling Perl extensions completely:

    URxvt.perl-ext-common:

To selectively disable an extension, you need to prepend a hyphen before the extension name:

    Urxvt.perl-ext-common: default,-extension

Alternatively, you can explicitly list every extension you need, effectively disabling all others:

    URxvt.perl-ext-common: eval,searchable-scrollback,resize-font

## Troubleshooting

### Wrong shell prompt placement after upgrading to 9.31

Some window managers may have the problem that your prompt appears somewhere in the middle of the window. It may happens on start and/or on window resize. The root cause is update in lines-rewrap algorithm.

To solve the problem you should apply lines-rewrap.patch.

You can also play with geometry, but result is environment– and workflow–dependent, there is no "one size fits all" solution:

- Set the real geometry: `URxvt.geometry: 174x47`.
- Set unrealistic geometry: `URxvt.geometry: 400x400`.
- Set rows to -1: `URxvt.geometry: 80x-1`.

    This may lead to inability to use some command line options, for example `urxvt --borderColor black -e mc` sometimes opens the terminal for a fraction of second with shell prompt placed in the middle of the first row instead of running Midnight Commander.

Ultimate solution is reverting changes in the source code:

- Comment out one line in `screen.C` (also see `starttop.patch`).
- Fully revert algorithm changes: FS#77062#comment216001.

### Remote hosts

If you are logging into a remote host, you may encounter problems when running text-mode programs under rxvt-unicode. This can be fixed by installing rxvt-unicode-terminfo on the remote host or by copying `/usr/share/terminfo/r/rxvt-unicode` from your local machine to your host at `~/.terminfo/r/rxvt-unicode`; same for `rxvt-unicode-256color`.

Some remote systems do not change title automatically unless you specify `TERM=xterm`. To fix the issue add this line to `.bashrc` on the remote machine:

    PROMPT_COMMAND='echo -ne "\033]0;${USER}@${HOSTNAME}:${PWD}\007"'

Another fix you can try is to put following in your `.Xresources`:

    URxvt.termName: rxvt

This is useful when connecting into remote hosts without admin privileges to install terminfo definition for rxvt-unicode.

### Using rxvt-unicode as gmrun terminal

Unlike some other terminals, urxvt expects the arguments to `-e` to be given separately, rather than grouped together with quotes. This causes trouble with gmrun, which assumes the opposite behavior. This can be worked around by putting an `eval` in front of gmrun's `Terminal` variable in `.gmrunrc`:

    Terminal = eval urxvt
    TermExec = ${Terminal} -e

gmrun uses `/bin/sh` to execute commands, so the `eval` is understood here. The `eval` has the side-effect of "breaking up" the argument to `-e` in the same way that `$@` does in Bash, making the command intelligible to urxvt.

### My numerical keypad acts weird and generates differing output? (e.g. in vim)

This article or section is being considered for removal.

Reason: I would like to remove this section: (a) It's more than 10 years old, the code has changed a lot. (b) Maybe it's Debian GNU/Linux-related only (see the first sentence). Do you have this issue with current version in Arch? (c) xmodmap is deprecated and often cause troubles, especially if it is used in conjunction with setxkbmap, if the issue is still relevant - it's better to advise to learn xkb. (Discuss in Talk:Rxvt-unicode)

Some Debian GNU/Linux users seem to have this problem, although no specific details were reported so far. It is possible that this is caused by the wrong TERM setting, although the details of whether and how this can happen are unknown, as TERM=rxvt should offer a compatible keymap.

However, using the xmodmap program (xorg-xmodmap), you can re-map your number pad keys back.

1. Check the keycode that your numerical keypad (numpad) generates using `xev` program.

- Start the `xev` program
- Press your number pad keys and look for ... keycode xxx ... in `xev`'s output. For example, numpad 1 in some keyboards is also "End" key, that have a 'keycode 87'.

2. Create or modify your xmodmap file, usually `~/.Xmodmap`, with the content representing your keycode.

Example of xmodmap file with number pad keycode:

    keycode 63 = KP_Multiply
    keycode 79 = Home KP_7
    keycode 80 = Up KP_8
    keycode 81 = Prior KP_9
    keycode 82 = KP_Subtract
    keycode 83 = Left KP_4
    keycode 84 = KP_5
    keycode 85 = Right KP_6
    keycode 86 = KP_Add
    keycode 87 = End KP_1
    keycode 88 = Down KP_2
    keycode 89 = Next KP_3
    keycode 90 = Insert KP_0
    keycode 91 = Delete KP_Decimal
    keycode 112 = Prior
    keycode 117 = Next

3. Load your xmodmap file at X session start-up.

For example, in `~/.xinitrc` file add:

    ...
    xmodmap ~/.Xmodmap
    ...

### Key combinations do not work

See Get Alt key to work in terminal.

### Very long lines cause slowdown

The `matcher` plugin may be the culprit here. It must match a regex against a line every time the line updates, and if you have a large `saveLines` value this can exacerbate the problem by allowing a very large maximum line length.

There are some simple workarounds:

- Reduce `saveLines`
- Disable the `matcher` plugin

If neither of those are palatable options, you can compromise by disabling URL matching past a certain cutoff point:

1. Copy `/usr/lib/urxvt/perl/matcher` to `~/.urxvt/ext/` (creating the directory if necessary)
2. Edit `~/.urxvt/ext/matcher`, and find the `my ($self, $row) = @_;` line in the `on_line_update` sub. It should be line 270.
3. After that line, insert the line `return () if $row < -100;`. This disables URL matching on any line that starts more than 100 rows behind the top of the terminal.

## See also

- Rxvt Unicode — video tutorial by Alex Booker
- Browsable CVS — the source code
- rxvt-unicode — `enable-wide-glyphs.patch` developer's dotfile

Category:

- Terminal emulators

Hidden categories:

- Pages or sections flagged with Template:Out of date
- Sections flagged with Template:Remove