[Documentation] [TitleIndex] [WordIndex

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:

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.


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

export ROS_ROOT=/home/user/ros/ros


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/

export PATH=$ROS_ROOT/bin:$PATH


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 is an optional, but very common environment variable that allows you to add more ROS packages to your ROS path. 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 ROS_PACKAGE_PATH is searched recursively--all ROS packages below the named path will be found.

System Data Environment Variables


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).


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.


Directory that test results should be written to.

Additional Bash Environment Variables


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 =s. For example:

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

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

Node Environment Variables


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. 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 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.


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

New in CTurtle

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.


New in Diamondback

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:


Build System Environment Variables

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


NOTE: Removed in CTurtle. You should instead set the standard CPATH, LIBRARY_PATH and LD_LIBRARY_PATH variables

ROS_BINDEPS_PATH is an optional environment variable for the case that you don't install 3rdparty dependencies (eg. log4cxx) into /opt/ros. Set this to the path where they are installed.


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


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:

export ROS_PARALLEL_JOBS=-j -l8

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


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.


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

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.


New in Diamondback 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.

2011-11-19 12:17