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/fuerte/setup.bash.
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, ROS_PACKAGE_PATH becomes obsolete, and will be kept only 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 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.
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.
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 client libraries that should be disabled. Message-generation will not happen for packages in this list. E.g.:
export ROS_LANG_DISABLE=roslisp:rosjava
New in Groovy If the package responsible for generating the messages for a specific languages uses catkin (which is true for most message generators as of Groovy) the package name should be the package which does the actual generation of the messages. E.g.:
export ROS_LANG_DISABLE=genlisp:genjava
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" This will force it to detect Ubuntu Lucid:
export ROS_OS_OVERRIDE=ubuntu:10.04
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.