From Gentoo Wiki
Jump to:navigation Jump to:search
This page contains changes which are not marked for translation.

Bugs which cannot be reproduced on Arch GNU/Linux might be ignored by upstream!

rxvt-unicode, also known simply as urxvt, is a fast and lightweight terminal emulator with Xft and Unicode support.

Many Gentoo users enjoy using urxvt inside the i3 and Sway window managers.


USE flags

USE flags for x11-terms/rxvt-unicode rxvt clone with xft and unicode support

256-color Enable 256 color support
blink Enable blinking text
fading-colors Enable colors fading when off focus
font-styles Enable support for bold and italic fonts
gdk-pixbuf Enable transparency support using x11-libs/gdk-pixbuf
iso14755 Enable ISO-14755 support
mousewheel Enable scrolling via mouse wheel or buttons 4 and 5
perl Enable perl script support. You can still disable this at runtime with -pe ""
startup-notification Enable application startup event feedback mechanism
unicode3 Use 21 instead of 16 bits to represent unicode characters
utmp Enable utmp support
wtmp Enable wtmp support
xft Build with support for XFT font renderer (x11-libs/libXft)


Install x11-terms/rxvt-unicode:

root #emerge --ask rxvt-unicode


It is possible to operate urxvt as a daemon, which will lead to lower resource usage and quicker startup for new terminals. It is a good idea to start the daemon at the beginning of the X session.

The following command will start the daemon and fork it into the background.

user $urxvtd --quiet --opendisplay --fork

After this, new clients can be opened on the single daemon process, rather than spawning new processes for each terminal. To do this, simply run urxvtc in place of the usual urxvt command. Keep in mind that if for any reason the daemon is terminated, any subsequent urxvtc calls as well all client instances will be closed.

Environment variable can be used to specify different location for the daemon ~/.urxvt/urxvtd-hostname listening socket.

CODE The socket location as environment variable
export RXVT_SOCKET='/tmp/urxvt-socket'


Configuration for urxvt is done mainly through the X resources system, though command line equivalents are also available in most cases. A full list of these options can be found in the urxvt manpage. To configure all urxvt options in a different file and including this file in .Xresources my be advisable. For example:

FILE ~/.Xresources
#include ".config/urxvt"

Some common configuration options are listed below.

It is recommended to become familiar with the X resources syntax before editing the configuration.


urxvt's font can be configured using either XLFD notation or, provided the package was compiled with the xft USE flag, Xft fonts.

FILE ~/.Xresources
! Using XLFD (created via e.g. xfontsel)
URxvt*font:           -misc-fixed-medium-r-semicondensed-*-12-90-100-*-c-60-iso8859-1
! Using Xft
URxvt*font:           xft:Inconsolata:size=8

Fonts can be modified while urxvt is running by assigning actions to keys:

FILE ~/.Xresources
! Bind C-p to use unifont and show 'halfwidth left corner bracket', U+FF62,「
URxvt.keysym.C-p: 	command:\033]710;xft:Unifont:pixelsize=20\007
! Bind C--, C-0(=) and C-+ to activate small, medium, and big font size resp. 
URxvt.keysym.C-minus: 	command:\033]710;xft:Liberation Mono:pixelsize=12\007
URxvt.keysym.C-0:	command:\033]710;xft:DejaVu Sans Mono:pixelsize=16\007
URxvt.keysym.C-plus:	command:\033]710;xft:Liberation Mono:pixelsize=20\007
In some fonts, depending on the font size, Unicode may not work properly.

Rendering settings can be tweaked for Xft fonts as well. Note that this is not specific to urxvt.

FILE ~/.Xresources
Xft.dpi:        96
Xft.antialias:  true
Xft.rgba:       rgb
Xft.hinting:    true
Xft.hintstyle:  hintslight
Xft.autohint:   false
Xft.lcdfilter:  lcddefault


The look of the scrollbar can be changed, or it can be removed entirely.

FILE ~/.Xresources
URxvt.scrollBar: false
URxvt.scrollBar_right: false
URxvt.scrollBar_floating: false
URxvt.scrollstyle: rxvt


By default, urxvt will print out a screen dump, via lpr, when PrntScrn is pressed. Using Ctrl+PrintScrn or Shift-PrintScrn will include the terminal's scroll back in the printout as well. This behavior can be changed, or disabled entirely, based on personal preference and need.

FILE ~/.Xresources
! The string will be interpreted as if typed into the shell as-is.
! In this example, printing will be disabled altogether.
URxvt.print-pipe: "cat > /dev/null"

Copy/Paste and URL handling

The default urxvt Perl extensions can be used for copy and paste actions as well for URL handling capabilities. In order to use Perl extensions in urxvt, the package must have been compiled with the perl USE flag. The x11-misc/urxvt-perls package provides the keyboard-select extension not included by default. The package sources code can be found in muennich's GitHub repository or an ebuild for example. It is possible to get other Perl extensions.

Here is an example of a ~/.Xresources. The following lines could also be added to ~/.Xdefaults, though ~/.Xresources is preferred.

FILE ~/.Xresources
!-*- Perl extensions -*-
URxvt.perl-ext-common: default,selection-to-clipboard,pasta,matcher,keyboard-select
URxvt.keysym.M-u:     perl:url-select:select_next
URxvt.url-launcher:   /usr/bin/firefox
URxvt.underlineURLs:  True
URxvt.matcher.button: 1 
URxvt.keysym.Control-Shift-V:     perl:pasta:paste
! Comment this if you don't want copy when text is selected
URxvt.clipboard.autocopy: true

The default selection-to-clipboard extension will put the selected text into the clipboard automatically. To add pasting functionality we have to create a simple extension:

FILE /usr/lib/urxvt/perl/pasta
#! /usr/bin/env perl -w
# Author:   Aaron Caffrey
# Website:  https://github.com/wifiextender/urxvt-pasta
# License:  GPLv3

# Usage: put the following lines in your .Xdefaults/.Xresources:
# URxvt.perl-ext-common           : selection-to-clipboard,pasta
# URxvt.keysym.Control-Shift-V    : perl:pasta:paste

use strict;

sub on_user_command {
  my ($self, $cmd) = @_;
  if ($cmd eq "pasta:paste") {
    $self->selection_request (urxvt::CurrentTime, 3);


Menu icon

This adds menu entry and menu icon for urxvt. If urxvt doesn't have a .desktop file, create one.

FILE /usr/share/applications/urxvt.desktop
[Desktop Entry]
Comment=Terminal emulator
# This assumes the 'startup-notification' USE flag being enabled

Application icon

For setting application icon x11-terms/rxvt-unicode has to be compiled with pixbuf USE flag.

FILE ~/.Xresources
URxvt.iconFile:    /usr/share/icons/hicolor/scalable/apps/Terminal.svg

Color theme

The main urxvt's color palette is defined by background, foreground and colorn resources. It is also possible to set color of other elements (e.g. cursor or text underline). For more information consult the urxvt manpage.

FILE ~/.Xresources
*background: #0f0f0f
*foreground: #c8c8c8

*color0:  #251f1f
*color8:  #5e5e5e
*color1:  #eb4509
*color9:  #eb4509
*color2:  #94e76b
*color10: #95e76b
*color3:  #ffac18
*color11: #ffac18
*color4:  #46aede
*color12: #46aede
*color5:  #e32c57
*color13: #e32c57
*color6:  #d6dbac
*color14: #d6dbac
*color7:  #efefef
*color15: #efefef
FILE ~/.XresourcesTango colors
! black
*color0:  #2E3436
*color8:  #555753
! red
*color1:  #a40000
*color9:  #EF2929
! green
*color2:  #4E9A06
*color10: #8AE234
! yellow
*color3:  #C4A000
*color11: #FCE94F
! blue
*color4:  #3465A4
*color12: #729FCF
! purple
*color5:  #75507B
*color13: #AD7FA8
! orange (replaces cyan)
*color6:  #ce5c00
*color14: #fcaf3e
! white
*color7:  #babdb9
*color15: #EEEEEC
FILE ~/.XresourcesLinux colors
! Colors
URxvt*background: #000000
URxvt*foreground: #B2B2B2
! black
URxvt*color0:  #000000
URxvt*color8:  #686868
! red
URxvt*color1:  #B21818
URxvt*color9:  #FF5454
! green
URxvt*color2:  #18B218
URxvt*color10: #54FF54
! yellow
URxvt*color3:  #B26818
URxvt*color11: #FFFF54
! blue
URxvt*color4:  #1818B2
URxvt*color12: #5454FF
! purple
URxvt*color5:  #B218B2
URxvt*color13: #FF54FF
! cyan
URxvt*color6:  #18B2B2
URxvt*color14: #54FFFF
! white
URxvt*color7:  #B2B2B2
URxvt*color15: #FFFFFF

Using urxvt with Powerline fonts

Unfortunately current default urxvt configuration in Gentoo breaks support for Powerline characters. Overview of the problem: some fonts provide incorrect values for character width, which breaks their appearance in urxvt in various ways.

The Powerline symbols are extra Unicode characters, which can be added to a font by "patching" it, or they can be added to the system without patching, using fontconfig settings. These fonts often contain wrong width set for the Powerline characters. Some other terminals workaround that, but not urxvt.

To get Powerline symbols to work correctly, you need the following USE flags to x11-terms/rxvt-unicode:

  • vanilla - disables the equally problematic alt-font-width
  • unicode3
  • 256-color - enables the required support of displaying 256 colors

For app-misc/powerline from the raiagent overlay, enable USE flag:

  • fonts, which will pull in media-fonts/powerline-fonts package.

For media-fonts/powerline-fonts (also from the raiagent overlay), enable one or more USE flags for the fonts you care about, e.g. inconsolata.

The installation of patched fonts from media-fonts/powerline-fonts package is the preferred installation method according the Powerline documentation. The alternative method using the standard fonts and enabling Gentoo's media-fonts/powerline-symbols via Fontconfig does not seem to work for urxvt. Nevertheless, the media-fonts/powerline-symbols is a mandatory dependency of app-misc/powerline so it gets installed anyway.

Finally, in the ~/.Xresources file, set a desired Powerline font for urxvt. This example assumes the xft USE flag for x11-terms/rxvt-unicode, but the main point is to enable the font featuring for Powerline name part.

FILE ~/.Xresourcesurxvt Powerline font configuration
URxvt*font:   xft:Inconsolata for Powerline:size=11
After making changes to ~/.Xresources, you need to run a command like
user $xrdb ~/.Xresources
to let the changes have effect.

See also rxvt-unicode and the Powerline symbols thread on the urxvt mailing list.

Changing font size on the fly

To be able to use font size changing within running terminal session, first verify urxvt has been build using the perl USE flag.

Install the x11-misc/urxvt-font-size package:

root #emerge --ask x11-misc/urxvt-font-size

Open the ~/.Xresources file for editing and replace the entry:

FILE ~/.Xresources
!-*- Perl extensions -*-
URxvt.perl-ext-common: default,selection-to-clipboard,pasta,matcher,keyboard-select

With following entry, or just add the font-size to the end of the listed extensions:

FILE ~/.Xresources
!-*- Perl extensions -*-
URxvt.perl-ext-common: default,selection-to-clipboard,pasta,matcher,keyboard-select,font-size

Configure a keyboard key combination to increase or decrease the font size, add following entries:

FILE ~/.Xresources
URxvt.keysym.C-Up:     font-size:increase
URxvt.keysym.C-Down:   font-size:decrease
URxvt.keysym.C-S-Up:   font-size:incglobal
URxvt.keysym.C-S-Down: font-size:decglobal
URxvt.keysym.C-equal:  font-size:reset
URxvt.keysym.C-slash:  font-size:show

To increase the font size press Ctrl++, to decrease the font size press Ctrl+-. To reset to the default font size press Ctrl+0.


Changes in ~/.Xresources are not applied

1. Check for syntax errors in ~/.Xresources based on X_resources article.

2. If you're using ~/.xinitrc add [[ -f ~/.Xresources ]] && xrdb -merge ~/.Xresources to ~/.xinitrc and reboot.

3. Invoking `xrdb -merge -I$HOME ~/.Xresources`might also resolve the issue.

Reporting bugs

This 'Reporting bugs' section is satire.

This section describes the instructions for reporting and fixing urxvt bugs.

  1. Install Arch GNU/Linux.
    1. Test on Arch to see if the bug persists.
      1. If the bug does not persist, then contact the ebuild maintainer Jeroen Roovers (jer). The ebuild maintainer may be able to make a fix.
  2. Contact upstream developer. Be sure to note testing was performed on Gentoo Linux as Gentoo GNU/Linux or you will be ignored and possibly yelled at.
  3. When all else fails, contact the maintainer Jeroen Roovers (jer) and fix it this way.

These instructions are based on official upstream instructions from the developer.

See also

  • X resources — configuration options for X applications
  • Fonts — a core part of the system and are necessary in order to represent text on a display.

External resources