Contents

There are many environment variables that you can set to affect the behavior of ROS. Of these, the most important to understand are ROS_MASTER_URI, ROS_ROOT, and ROS_PACKAGE_PATH as they are commonly used in the system and frequently mentioned in documentation.

Environment variables serve a variety of roles in ROS:

Finding packages: First and foremost, the ROS_ROOT and ROS_PACKAGE_PATH enable ROS to locate packages and stacks in the filesystem. You must also set the PYTHONPATH so that the Python interpreter can find ROS libraries.
Effecting a Node runtime: There are also several ROS environment variables that effect how a Node runs. The ROS_MASTER_URI is an important environment variable that tells a Node where the Master is. ROS_IP and ROS_HOSTNAME affect the network address of a Node and ROS_NAMESPACE lets you change its namespace. ROS_LOG_DIR lets you set the directory where log files are written. Many of these can be overridden by Remapping Arguments as well, which have precedence over environment variables.
Modifying the build system: ROS_BINDEPS_PATH, ROS_BOOST_ROOT, ROS_PARALLEL_JOBS, and ROS_LANG_DISABLE affect where libraries are found, how they are built, and which ones are built.

These environment variables and more are described in greater detail below.

Required ROS Environment Variables

Most systems will also have ROS_PACKAGE_PATH set, but the only required environment variables for ROS are ROS_ROOT, ROS_MASTER_URI, and PYTHONPATH. By default these are automatically set for you by sourcing /opt/ros/ROSDISTRO/setup.bash. (Replace ROSDISTRO with the desired ROS distribution, e.g. indigo.)

ROS_ROOT

ROS_ROOT sets the location where the ROS core packages are installed.

export ROS_ROOT=/home/user/ros/ros
export PATH=$ROS_ROOT/bin:$PATH

ROS_MASTER_URI

ROS_MASTER_URI is a required setting that tells nodes where they can locate the master. It should be set to the XML-RPC URI of the master. Great care should be taken when using localhost, as that can lead to unintended behaviors with remotely launched nodes.

export ROS_MASTER_URI=http://mia:11311/

PYTHONPATH

ROS requires that your PYTHONPATH be updated, even if you don't program in Python! Many ROS infrastructure tools rely on Python and need access to the roslib package for bootstrapping.

export PYTHONPATH=$PYTHONPATH:$ROS_ROOT/core/roslib/src

Additional PATH Environment Variables

ROS_PACKAGE_PATH

ROS_PACKAGE_PATH is an optional, but very common environment variable that allows you to add more ROS packages from source to your environment. ROS_PACKAGE_PATH can be composed of one or more paths separated by your standard OS path separator (e.g. ':' on Unix-like systems). These ordered paths tell the ROS system where to search for more ROS packages. If there are multiple packages of the same name, ROS will choose the one that appears on ROS_PACKAGE_PATH first.

export ROS_PACKAGE_PATH=/home/user/ros/ros-pkg:/another/path

Note that each entry in ROS_PACKAGE_PATH is searched recursively--all ROS packages below the named path will be found.

With the introduction of catkin, the need to manually update ROS_PACKAGE_PATH becomes obsolete, and is only necessary for backwards compatibility with rosbuild packages.

System Data Environment Variables

ROS_HOME

By default, ROS writes data to ~/.ros. This location can be changed by setting an optional ROS_HOME. You can also change the location of certain individual directories in ~/.ros (e.g. ROS_TEST_RESULTS_DIR, ROS_LOG_DIR).

ROS_LOG_DIR

By default, ROS writes internal log files to ROS_HOME/log. If this location is not writable to ROS, or if you wish for log files to be written elsewhere, set ROS_LOG_DIR to that path.

ROS_TEST_RESULTS_DIR

Directory that test results should be written to.

ROS_CACHE_TIMEOUT

(See rospack's api doc for the detail).

rospack re-parses the package.xml files and rebuilds the dependency tree on each execution. However, it maintains a cache of package directories in ROS_ROOT/.rospack_cache. This cache is updated whenever there is a cache miss, or when the cache is 60 seconds old. You can change this timeout by setting the environment variable ROS_CACHE_TIMEOUT, in seconds. Set it to 0.0 to force a cache rebuild on every invocation of rospack.

Additional Bash Environment Variables

ROS_LOCATIONS

ROS_LOCATIONS is an optional environment variable that provides keyed names for useful locations. It is a : separated list of key-location pairs. Each key-location pair is separated by an =. For example:

export ROS_LOCATIONS="rospkg=/path/to/rospkg:stairpkg=/path/to/stairpkg"

These keys can then be used in tools such as roscd.

ROS_WORKSPACE

ROS_WORKSPACE is introduced by the rosinstall / rosws tools, it is set by setup.sh that is generated by these tools when creating a workspace. It points to the folder of the workspace and is used by the rosws command as a default target of the command.

The roscd tool in fuerte was also changed to use that variable when called without arguments. Previously it had defaulted to change to ROS_ROOT.

Node Environment Variables

ROS_IP/ROS_HOSTNAME

ROS_IP and ROS_HOSTNAME are optional environment variable that sets the declared network address of a ROS Node or tool. The options are mutually exclusive, if both are set ROS_HOSTNAME will take precedence. Use ROS_IP if you are specifying an IP address, and ROS_HOSTNAME if you are specifying a host name. When a ROS component reports a URI to the master or other components, this value will be used. This setting is only needed in situations where you have multiple addresses for a computer and need to force ROS to a particular one.

With the exception of 'localhost', it does not affect the actual bound address as ROS components bind to all available network interfaces. If the value is set to localhost, the ROS component will bind only to the loopback interface. This will prevent remote components from being able to talk to your local component.

ROS_NAMESPACE

ROS_NAMESPACE lets you push down a Node into a namespace. All of the names in the Node will be resolved relative to this value, including remapped names.

ROSCONSOLE_CONFIG_FILE

This is a roscpp-specific environment variable. rosconsole lets you define your own configuration file that will be used by log4cxx, defined by the ROSCONSOLE_CONFIG_FILE environment variable. Anything defined in this config file will override the default config file.

See doc/api/rosconsole/html/index.html for more information.

Console Output Formatting

rosconsole allows you to specify how you'd like its output to show up in the console output through the ROSCONSOLE_FORMAT environment variable. The default is equivalent to:

export ROSCONSOLE_FORMAT='[${severity}] [${time}]: ${message}'

See doc/api/rosconsole/html/index.html for more information on this package in general. You can see the list of parsed format strings in the source code.

ROS_PYTHON_LOG_CONFIG_FILE

This is specific to rospy, rosmaster, roslaunch, and rostest. For these tools, you can define your own Python logging configuration file to use instead of the default config file, which is stored in $ROS_ROOT/config/python_logging.conf.

For more information, see the Python logging documentation:

http://docs.python.org/library/logging.html

Build System Environment Variables

In order to understand these environment variables better, please see the section on the ROS Build System.

ROS_BOOST_ROOT

ROS_BOOST_ROOT is an optional environment variable that lets you override where to search for boost. If ROS_BOOST_ROOT is not set it defaults to using ROS_BINDEPS_PATH

ROS_PARALLEL_JOBS

The value of this variable, if set, is passed to make when building packages. The idea is to let you exploit a multi-processor machine. For example, if you have 8 processors / cores and want to run as many parallel jobs as possible, as long as the system load is less than 8, by limiting the jobs to 8 you prevent overshoot at startup time:

export ROS_PARALLEL_JOBS='-j8 -l8'

Alternatively, you could use the -j flag with an argument to run up to 8 jobs in parallel, independent of system load:

export ROS_PARALLEL_JOBS=-j8

We strongly recommend using the -l flag to set a system load-dependent limit on parallelism. Excessive parallelism in a large build can exhaust system memory.

What system load is acceptable to you depends on how many cores you have: http://blog.scoutapp.com/articles/2009/07/31/understanding-load-averages

So 8 might be suitable for a machine with 8 cores.

ROS_LANG_DISABLE

A colon-separated list of package names for message generators / client libraries that should be disabled. Message-generation will not happen for languages in this list.

For packages build with catkin you need to list the names of the message generators which should be ignored, e.g.:

export ROS_LANG_DISABLE=genlisp

For packages build with rosbuild you need to list the names of the message generators as well as the client libraries which should be ignored, e.g.:

export ROS_LANG_DISABLE=genlisp:roslisp

When ignoring message generators with rosbuild the CMake configure step will show a warning that the client library (e.g. roslisp) is not a known message generator. This warning can safely be ignored.

Note that before disabling a language, you should first be very sure that none of the code you're using requires that language's bindings.

ROS_OS_OVERRIDE

Format: "OS_NAME:OS_VERSION_STRING:OS_CODENAME" This will force it to detect Ubuntu Bionic:

export ROS_OS_OVERRIDE=ubuntu:18.04:bionic

If defined, this will override the autodetection of an OS. This can be useful when debugging rosdep dependencies on alien platforms, when platforms are actually very similar and might need be forced, or of course if the autodetection is failing.