eselect

From Gentoo Wiki
Jump to:navigation Jump to:search
This page contains changes which are not marked for translation.
Other languages:
Portage - the heart of Gentoo
emerge — configuration — ebuild repository — dispatch-conf

world file — USE flags — ebuilds — profiles
upgrades — using testing packages — binary packages
tools — gentoolkit — eselect
Portage FAQ — cheat sheet — FAQ
all articles

eselect is a tool for administration and configuration on Gentoo systems. It modifies the system's behavior and should be used with care by the system administrator. eselect is a modular framework for writing configuration utilities, consisting of:

  • a main program named eselect (found in app-admin/eselect)
  • various modules (*.eselect files) which carry out different tasks
  • several libraries which help to ensure consistent behavior and simplify the creation of new modules


A module provides several actions. Actions typically either display some information (list and show actions are common) or update the system somehow (for example, set and update). Each module also provides help and usage actions which explain how to use the module.

To list all currently installed modules, run eselect without any arguments. See also the eselect user guide.

Installation

Deployments of Gentoo Linux should already have eselect installed, as the app-admin/eselect package is part of the system set.

USE flags

USE flags for app-admin/eselect Gentoo's multi-purpose configuration and management tool

doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
emacs Add support for GNU Emacs
vim-syntax Pulls in related vim syntax scripts
Data provided by the Gentoo Package Database · Last update: 2025-10-24 17:41 More information about USE flags

Emerge

After USE flag changes

After changing USE flags just for the eselect package, rebuild eselect for the new flags to be applied. As eselect is in the system set, --oneshot should be used to avoid adding it to the world file:

root #emerge --ask --changed-use --oneshot app-admin/eselect

After changing any global USE flags in make.conf that affect the eselect package, emerge world to update to the new USE flags:

root #emerge --ask --verbose --update --deep --newuse @world

Modules

Install an eselect module just like any other package. For example, for the app-eselect/eselect-repository module:

root #emerge --ask --verbose app-eselect/eselect-repository

Some modules will be pulled in when installing packages that depend on them.

See the modules section for information on finding optional modules for installation.

Invocation

Just running eselect, or eselect help for a little more information, will provide usage information and list all installed modules and their function:

root #eselect help
Usage: eselect <global options> <module name> <module options>

Global options:
  --brief                   Make output shorter
  --colour=<yes|no|auto>    Enable or disable colour output (default 'auto')

Built-in modules:
  help                      Display a help message
  usage                     Display a usage message
  version                   Display version information

Extra modules:
  arptables                 Manage the iptables/arptables/ebtables symlinks
  binutils                  Manage installed versions of sys-devel/binutils
  cdparanoia                Manage /usr/bin/cdparanoia implementation
  ctags                     Manage /usr/bin/ctags implementations
  ebtables                  Manage the iptables/arptables/ebtables symlinks
  editor                    Manage the EDITOR environment variable
  emacs                     Manage /usr/bin/emacs version
  env                       Manage environment variables set in /etc/env.d/
  etags                     Manage /usr/bin/etags implementations
  fontconfig                Manage fontconfig /etc/fonts/conf.d/ symlinks
  gcc                       Manage installed versions of sys-devel/gcc
  gnuclient                 Manage /usr/bin/gnuclient implementations
  iptables                  Manage the iptables/arptables/ebtables symlinks
  kernel                    Manage the /usr/src/linux symlink
  locale                    Manage the LANG environment variable
  lua                       Manage lua symlinks
  modules                   Query eselect modules
  mpg123                    Manage /usr/bin/mpg123 implementation
  news                      Read Gentoo ("GLEP 42") news items
  notify-send               Manage /usr/bin/notify-send implementation
  pager                     Manage the PAGER environment variable
  pinentry                  Manage /usr/bin/pinentry implementation
  postgresql                Manage active PostgreSQL client applications and libraries
  profile                   Manage the make.profile symlink
  rc                        Manage /etc/init.d scripts in runlevels
  repository                Manage repository list in repos.conf
  rust                      Manage the Rust compiler versions
  sh                        Manage /bin/sh (POSIX shell) implementations
  vi                        Manage /usr/bin/vi implementations
  visual                    Manage the VISUAL environment variable
  wxwidgets                 Manage the system default wxWidgets profile

Modules

Gentoo has tens of eselect modules available, to automate various system configuration tasks. Several modules allow to select between optional subsytems, such as which installed vi editor package to use or which emacs distribution to be default.

Some modules are shipped by default with eselect, while other modules can be installed from the Gentoo repository.

To list all modules currently installed, run eselect without any arguments.

Default modules

These modules are maintained as part of the eselect project, so they should be available as long as the app-admin/eselect package is installed.

Arptables, iptables, and ebtables

Manage the iptables/arptables/ebtables symlinks. Because sys-apps/iproute2 is part of the system set, app-eselect/eselect-iptables is often pulled in by the dependency graph, to provide these modules.

user $eselect arptables help
Manage the iptables/arptables/ebtables symlinks
Usage: eselect arptables <action> <options>

Standard actions:
  help                      Display help text
  usage                     Display usage information
  version                   Display version information

Extra actions:
  list                      List available arptables symlink targets
  set                       Set a new arptables symlink target
    target                    Target name or number (from 'list' action)
  show                      Show the current arptables symlink
  unset                     Unset arptables symlink targets

Binutils

Manage installed versions of sys-devel/binutils. This module is not provided as part of the app-admin/eselect package, but is from sys-devel/binutils-config, a dependency of sys-devel/binutils. As sys-devel/binutils is part of the system set, eselect binutils should be available on all Gentoo systems.

user $eselect binutils help
Manage installed versions of sys-devel/binutils
Usage: eselect binutils <action> <options>

Standard actions:
  help                      Display help text
  usage                     Display usage information
  version                   Display version information

Extra actions:
  list                      List all installed version of binutils
  set <target>              Activate one of the installed binutils
    target                    Target name or number (from 'list' action)
  show                      Print the currently active binutils version

Editor

Manage the EDITOR environment variable, this determines what many CLI programs will run to edit text files.

See also the visual module section.

user $eselect editor help
Manage the EDITOR environment variable

Usage: eselect editor <action> <options>

Standard actions: 

 help                      Display help text
 usage                     Display usage information
 version                   Display version information

Extra actions: 

 list                      List available targets for the EDITOR variable
 set <target>              Set the EDITOR variable in profile
   target                    Target name or number (from 'list' action)
 show                      Show value of the EDITOR variable in profile
 update                    Update the EDITOR variable if it is unset or invalid
See also
See setting default text editor.

Env

Manage environment variables set in /etc/env.d.

user $eselect env help
Manage environment variables set in /etc/env.d/
Usage: eselect env <action> <options>

Standard actions:
  help                      Display help text
  usage                     Display usage information
  version                   Display version information

Extra actions:
  update <noldconfig>       Collect environment variables from all scripts in /etc/env.d/
    noldconfig                Do not alter the ld.so cache or configuration.

Gcc

Manage installed versions of sys-devel/gcc. Because sys-devel/gcc is part of the system set, sys-devel/gcc-config will be pulled in, providing this module.

user $eselect gcc help
Manage installed versions of sys-devel/gcc
Usage: eselect gcc <action> <options>

Standard actions:
  help                      Display help text
  usage                     Display usage information
  version                   Display version information

Extra actions:
  list                      List all installed version of gcc
  set <target>              Activate one of the installed gcc
    target                    Target name or number (from 'list' action)
  show                      Print the currently active gcc version

See also upgrading GCC.

Kernel

The /usr/src/linux symlink should point to the currently running kernel, this can be done with eselect.

user $eselect kernel help
Manage the /usr/src/linux symlink
Usage: eselect kernel <action> <options>

Standard actions:
  help                      Display help text
  usage                     Display usage information
  version                   Display version information

Extra actions:
  list                      List available kernel symlink targets
  set <target>              Set a new kernel symlink target
    target                    Target name or number (from 'list' action)
  show                      Show the current kernel symlink

See setting the kernel link with eselect.

Locale

Manage the LANG environment variable, this sets the system language for users, date formats etc.

user $eselect locale help
Manage the LANG environment variable
Usage: eselect locale <action> <options>

Standard actions:
  help                      Display help text
  usage                     Display usage information
  version                   Display version information

Extra actions:
  list                      List available targets for the LANG variable
  set <target>              Set the LANG variable in profile
    target                    Target name or number (from 'list' action)
  show                      Show value of the LANG variable in profile

See the handbook, localization guide and UTF-8 article.

Modules

Query eselect modules.

user $eselect modules help
Query eselect modules
Usage: eselect modules <action> <options>

Standard actions:
  help                      Display help text
  usage                     Display usage information
  version                   Display version information

Extra actions:
  has <module>              Return true if the module is installed, and false otherwise
  list                      List all available modules
    --only-names              Output names of modules only

News

Read Gentoo ("GLEP 42") news items. It is important to read and follow these, when they are shown after a Gentoo ebuild repository synchronization.

user $eselect news help
Read Gentoo ("GLEP 42") news items
Usage: eselect news <action> <options>

Standard actions:
  help                      Display help text
  usage                     Display usage information
  version                   Display version information

Extra actions:
  count                     Display number of news items
    new                       Count unread news items (default)
    all                       Count all news items
  list                      List news items
  purge                     Purge read news
  read <item>...            Read news items
    --mbox                    Output in mbox format
    --quiet                   Suppress output, only change status
    --raw                     Output in raw format
    new                       Read unread news items (default)
    all                       Read all news items
    item                      Item name or number (from 'list' action)
  unread <item>...          Mark read news items as unread again
    all                       Mark all news items as unread
    item                      Item name or number (from 'list' action)

Pager

Manage the PAGER environment variable, this will influence what programs will use to display pages of text to the user.

user $eselect pager help
Manage the PAGER environment variable
Usage: eselect pager <action> <options>

Standard actions:
  help                      Display help text
  usage                     Display usage information
  version                   Display version information

Extra actions:
  list                      List available targets for the PAGER variable
  set <target>              Set the PAGER variable in profile
    target                    Target name or number (from 'list' action)
  show                      Show value of the PAGER variable in profile
  update                    Update the PAGER variable if it is unset or invalid

Profile

Manage the make.profile symlink, this is an important configuration item for Portage, and for the whole system.

user $eselect profile help
Manage the make.profile symlink
Usage: eselect profile <action> <options>

Standard actions:
  help                      Display help text
  usage                     Display usage information
  version                   Display version information

Extra actions:
  list                      List available profile symlink targets
  set <target>              Set a new profile symlink target
    target                    Target name or number (from 'list' action)
    --force                   Forcibly set the symlink
  show                      Show the current make.profile symlink

See handbook, and the article about profiles.

Rc

The eselect rc module, and thus its corresponding rc-config command, are deprecated as of version 1.4.30 (2025-03-22).

This module was used to manage OpenRC scripts, the rc-update, rc-service or rc-status commands can be used instead.

Visual

Manage the VISUAL environment variable, to set the default text editor for capable terminals.

See also the editor module section.

user $eselect visual help
Manage the VISUAL environment variable
Usage: eselect visual <action> <options>

Standard actions:
  help                      Display help text
  usage                     Display usage information
  version                   Display version information

Extra actions:
  list                      List available targets for the VISUAL variable
  set <target>              Set the VISUAL variable in profile
    target                    Target name or number (from 'list' action)
  show                      Show value of the VISUAL variable in profile
  update                    Update the VISUAL variable if it is unset or invalid
See also
See the text editor article.

Additional modules

Additional modules for eselect are available from the Gentoo ebuild repository.

Some of these modules will be pulled-in as dependencies when associated packages are installed, so it may not be required to emerge these specifically. Once installed, these modules can be used with eselect <module> commands, similarly to the default modules.

Here are some of the modules documented in the wiki:

See also

Retrieved from "https://wiki.gentoo.org/index.php?title=Eselect&oldid=1413846"