These instructions cover installing and uninstalling Robot Framework and its preconditions on different operating systems. If you already have pip installed, it is enough to run:
pip install robotframework
Robot Framework is implemented with Python and supports also Jython (JVM), IronPython (.NET) and PyPy. Before installing the framework, an obvious precondition is installing at least one of these interpreters.
Different ways to install Robot Framework itself are listed below and explained more thoroughly in the subsequent sections.
- Installing with pip
Using pip is the recommended way to install Robot Framework. As the standard Python package manager it is included in the latest Python, Jython and IronPython versions. If you already have pip available, you can simply execute:
pip install robotframework
- Installing from source
- This approach works regardless the operating system and the Python interpreter used. You can get the source code either by downloading a source distribution from PyPI and extracting it, or by cloning the GitHub repository .
- Standalone JAR distribution
- If running tests with Jython is enough, the easiest approach is downloading
the standalone
robotframework-<version>.jarfrom Maven central. The JAR distribution contains both Jython and Robot Framework and thus only requires having Java installed. - Manual installation
- If you have special needs and nothing else works, you can always do a custom manual installation.
Note
Prior to Robot Framework 3.0, there were also separate Windows installers for 32bit and 64bit Python versions. Because Python 2.7.9 and newer contain pip on Windows and Python 3 would have needed two more installers, it was decided that Windows installers are not created anymore. The recommend installation approach also on Windows is using pip.
Robot Framework is supported on Python (both Python 2 and Python 3), Jython (JVM) and IronPython (.NET) and PyPy. The interpreter you want to use should be installed before installing the framework itself.
Which interpreter to use depends on the needed test libraries and test environment in general. Some libraries use tools or modules that only work with Python, while others may use Java tools that require Jython or need .NET and thus IronPython. There are also many tools and libraries that run fine with all interpreters.
If you do not have special needs or just want to try out the framework, it is recommended to use Python. It is the most mature implementation, considerably faster than Jython or IronPython (especially start-up time is faster), and also readily available on most UNIX-like operating systems. Another good alternative is using the standalone JAR distribution that only has Java as a precondition.
Python 2 and Python 3 are mostly the same language, but they are not fully compatible with each others. The main difference is that in Python 3 all strings are Unicode while in Python 2 strings are bytes by default, but there are also several other backwards incompatible changes. The last Python 2 release is Python 2.7 that was released in 2010 and will be supported until 2020. See Should I use Python 2 or 3? for more information about the differences, which version to use, how to write code that works with both versions, and so on.
Robot Framework 3.0 is the first Robot Framework version to support Python 3. It supports also Python 2, and the plan is to continue Python 2 support as long as Python 2 itself is officially supported. We hope that authors of the libraries and tools in the wider Robot Framework ecosystem also start looking at Python 3 support now that the core framework supports it.
On most UNIX-like systems such as Linux and OS X you have Python installed by default. If you are on Windows or otherwise need to install Python yourself, a good place to start is http://python.org. There you can download a suitable installer and get more information about the installation process and Python in general.
Robot Framework 3.0 supports Python 2.6, 2.7, 3.3 and newer, but the plan is to drop Python 2.6 and 3.3 support in RF 3.1. If you need to use older versions, Robot Framework 2.5-2.8 support Python 2.5 and Robot Framework 2.0-2.1 support Python 2.3 and 2.4.
After installing Python, you probably still want to configure PATH to make
Python itself as well as the robot and rebot runner scripts
executable on the command line.
Tip
Latest Python Windows installers allow setting PATH as part of
the installation. This is disabled by default, but Add python.exe
to Path can be enabled on the Customize Python screen.
Using test libraries implemented with Java or that use Java tools internally requires running Robot Framework on Jython, which in turn requires Java Runtime Environment (JRE) or Java Development Kit (JDK). Installing either of these Java distributions is out of the scope of these instructions, but you can find more information, for example, from http://java.com.
Installing Jython is a fairly easy procedure, and the first step is getting
an installer from http://jython.org. The installer is an executable JAR
package, which you can run from the command line like java -jar
jython_installer-<version>.jar. Depending on the system configuration,
it may also be possible to just double-click the installer.
Robot Framework 3.0 supports Jython 2.7 which requires Java 7 or newer. If older Jython or Java versions are needed, Robot Framework 2.5-2.8 support Jython 2.5 (requires Java 5 or newer) and Robot Framework 2.0-2.1 support Jython 2.2.
After installing Jython, you probably still want to configure PATH to make
Jython itself as well as the robot and rebot runner scripts
executable on the command line.
IronPython allows running Robot Framework on the .NET platform and interacting with C# and other .NET languages and APIs. Only IronPython 2.7 is supported in general and IronPython 2.7.9 or newer is highly recommended.
If not using IronPython 2.7.9 or newer and Robot Framework 3.1 or newer, an additional requirement is installing ElementTree module 1.2.7 preview release. This is required because the ElementTree module distributed with older IronPython versions was broken. Once you have pip activated for IronPython, you can easily install ElementTree using this command:
ipy -m pip install http://effbot.org/media/downloads/elementtree-1.2.7-20070827-preview.zipAlternatively you can download the zip package, extract it, and install it by
running ipy setup.py install on the command prompt in the created directory.
After installing IronPython, you probably still want to configure PATH to make
IronPython itself as well as the robot and rebot runner scripts
executable on the command line.
PyPy is an alternative implementation of the Python language with both Python 2 and Python 3 compatible versions available. Its main advantage over the standard Python implementation is that it can be faster and use less memory, but this depends on the context where and how it is used. If execution speed is important, at least testing PyPY is probably a good idea.
Installing PyPy is a straightforward procedure and you can find both installers
and installation instructions at http://pypy.org. After installation you
probably still want to configure PATH to make PyPy itself as well as the
robot and rebot runner scripts executable on the command line.
The PATH environment variable lists locations where commands executed in
a system are searched from. To make using Robot Framework easier from the
command prompt, it is recommended to add the locations where the runner
scripts are installed into the PATH. It is also often useful to have
the interpreter itself in the PATH to make executing it easy.
When using Python on UNIX-like machines both Python itself and scripts
installed with should be automatically in the PATH and no extra actions
needed. On Windows and with other interpreters the PATH must be configured
separately.
Tip
Latest Python Windows installers allow setting PATH as part of
the installation. This is disabled by default, but Add python.exe
to Path can be enabled on the Customize Python screen. It will
add both the Python installation directory and the Scripts
directory to the PATH.
What directories you need to add to the PATH depends on the interpreter and
the operating system. The first location is the installation directory of
the interpreter (e.g. C:\Python27) and the other is the location
where scripts are installed with that interpreter. Both Python and IronPython
install scripts to Scripts directory under the installation directory
on Windows (e.g. C:\Python27\Scripts) and Jython uses bin
directory regardless the operating system (e.g. C:\jython2.7.0\bin).
Notice that the Scripts and bin directories may not be created as part of the interpreter installation, but only later when Robot Framework or some other third party module is installed.
On Windows you can configure PATH by following the steps below. Notice
that the exact setting names may be different on different Windows versions,
but the basic approach should still be the same.
- Open
Control Panel > System > Advanced > Environment Variables. There areUser variablesandSystem variables, and the difference between them is that user variables affect only the current users, whereas system variables affect all users. - To edit an existing
PATHvalue, selectEditand add;<InstallationDir>;<ScriptsDir>at the end of the value (e.g.;C:\Python27;C:\Python27\Scripts). Note that the semicolons (;) are important as they separate the different entries. To add a newPATHvalue, selectNewand set both the name and the value, this time without the leading semicolon. - Exit the dialog with
Okto save the changes. - Start a new command prompt for the changes to take effect.
Notice that if you have multiple Python versions installed, the executed
robot or rebot runner script will always use the one that is
first in the PATH regardless under what Python version that script is
installed. To avoid that, you can always execute the installed robot module
directly like C:\Python27\python.exe -m robot.
Notice also that you should not add quotes around directories you add into
the PATH (e.g. "C:\Python27\Scripts"). Quotes can cause problems with
Python programs and they are not needed
in this context even if the directory path would contain spaces.
On UNIX-like systems you typically need to edit either some system wide or user specific configuration file. Which file to edit and how depends on the system, and you need to consult your operating system documentation for more details.
If you are installing with pip and are behind a proxy, you need to set
the https_proxy environment variable. It is needed both when installing
pip itself and when using it to install Robot Framework and other Python
packages.
How to set the https_proxy depends on the operating system similarly as
configuring PATH. The value of this variable must be an URL of the proxy,
for example, http://10.0.0.42:8080.
The standard Python package manager is pip, but there are also other alternatives such as Buildout and easy_install. These instructions only cover using pip, but other package managers ought be able to install Robot Framework as well.
Latest Python, Jython, IronPython and PyPy versions contain pip bundled in. Which versions contain it and how to possibly activate it is discussed in sections below. See pip project pages if for the latest installation instructions if you need to install it.
Note
Robot Framework 3.1 and newer are distributed as wheels, but earlier versions are available only as source distributions in tar.gz format. It is possible to install both using pip, but installing wheels is a lot faster.
Note
Only Robot Framework 2.7 and newer can be installed using pip. If you need an older version, you must use other installation approaches.
Starting from Python 2.7.9, the standard Windows installer by default installs
and activates pip. Assuming you also have configured PATH and possibly
set https_proxy, you can run pip install robotframework right after
Python installation. With Python 3.4 and newer pip is officially part of the
interpreter and should be automatically available.
Outside Windows and with older Python versions you need to install pip yourself. You may be able to do it using system package managers like Apt or Yum on Linux, but you can always use the manual installation instructions found from the pip project pages.
If you have multiple Python versions with pip installed, the version that is
used when the pip command is executed depends on which pip is first in the
PATH. An alternative is executing the pip module using the selected Python
version directly:
python -m pip install robotframework
python3 -m pip install robotframeworkJython 2.7 contain pip bundled in, but it needs to be activated before using it by running the following command:
jython -m ensurepipJython installs its pip into <JythonInstallation>/bin directory.
Does running pip install robotframework actually use it or possibly some
other pip version depends on which pip is first in the PATH. An alternative
is executing the pip module using Jython directly:
jython -m pip install robotframeworkIronPython 2.7.5 and newer contain pip bundled in. With IronPython 2.7.9 and
newer pip also works out-of-the-box, but with earlier versions it needs to be
activated with ipy -m ensurepip similarly as with Jython.
With IronPython 2.7.7 and earlier you need to use -X:Frames command line
option when activating pip like ipy -X:Frames -m ensurepip and also
when using it. Prior to IronPython 2.7.9 there were problems creating
possible start-up scripts when installing modules. Using IronPython 2.7.9
is highly recommended.
IronPython installs pip into <IronPythonInstallation>/Scripts directory.
Does running pip install robotframework actually use it or possibly some
other pip version depends on which pip is first in the PATH. An alternative
is executing the pip module using IronPython directly:
ipy -m pip install robotframeworkAlso PyPy contains pip bundled in. It is not activated by default, but it can be activated similarly as with the other interpreters:
pypy -m ensurepip
pypy3 -m ensurepipIf you have multiple Python versions with pip installed, the version that is
used when the pip command is executed depends on which pip is first in the
PATH. An alternative is executing the pip module using PyPy directly:
pypy -m pip
pypy3 -m pipOnce you have pip installed, and have set https_proxy if you are behind a proxy, using pip on the command line is very easy. The easiest way to use pip is by letting it find and download packages it installs from the Python Package Index (PyPI), but it can also install packages downloaded from the PyPI separately. The most common usages are shown below and pip documentation has more information and examples.
# Install the latest version (does not upgrade)
pip install robotframework
# Upgrade to the latest version
pip install --upgrade robotframework
# Install a specific version
pip install robotframework==2.9.2
# Install separately downloaded package (no network connection needed)
pip install robotframework-3.0.tar.gz
# Install latest (possibly unreleased) code directly from GitHub
pip install https://github.com/robotframework/robotframework/archive/master.zip
# Uninstall
pip uninstall robotframeworkNotice that pip 1.4 and newer will only install stable releases by default.
If you want to install an alpha, beta or release candidate, you need to either
specify the version explicitly or use the --pre option:
# Install 3.0 beta 1
pip install robotframework==3.0b1
# Upgrade to the latest version even if it is a pre-release
pip install --pre --upgrade robotframeworkNotice that on Windows pip, by default, does not recreate robot.bat and
rebot.bat start-up scripts if the same Robot Framework version is installed
multiple times using the same Python version. This mainly causes problems
when using virtual environments, but is something to take into account
also if doing custom installations using pip. A workaround if using the
--no-cache-dir option like pip install --no-cache-dir robotframework.
Alternatively it is possible to ignore the start-up scripts altogether and
just use python -m robot and python -m robot.rebot commands instead.
This installation method can be used on any operating system with any of the supported interpreters. Installing from source can sound a bit scary, but the procedure is actually pretty straightforward.
You typically get the source code by downloading a source distribution from
PyPI. Starting from Robot Framework 3.1 the source distribution is a zip
package and with earlier versions it is in tar.gz format. Once you have
downloaded the package, you need to extract it somewhere and, as a result,
you get a directory named robotframework-<version>. The directory contains
the source code and a setup.py script needed for installing it.
An alternative approach for getting the source code is cloning project's GitHub repository directly. By default you will get the latest code, but you can easily switch to different released versions or other tags.
Robot Framework is installed from source using Python's standard setup.py
script. The script is in the directory containing the sources and you can run
it from the command line using any of the supported interpreters:
python setup.py install
jython setup.py install
ipy setup.py install
pypy setup.py installThe setup.py script accepts several arguments allowing, for example,
installation into a non-default location that does not require administrative
rights. It is also used for creating different distribution packages. Run
python setup.py --help for more details.
Robot Framework is also distributed as a standalone Java archive that contains both Jython and Robot Framework and only requires Java a dependency. It is an easy way to get everything in one package that requires no installation, but has a downside that it does not work with the normal Python interpreter.
The package is named robotframework-<version>.jar and it is available
on the Maven central. After downloading the package, you can execute tests
with it like:
java -jar robotframework-3.0.jar mytests.robot
java -jar robotframework-3.0.jar --variable name:value mytests.robotIf you want to post-process outputs using Rebot or use other built-in
supporting tools, you need to give the command name rebot, libdoc,
testdoc or tidy as the first argument to the JAR file:
java -jar robotframework-3.0.jar rebot output.xml
java -jar robotframework-3.0.jar libdoc MyLibrary listFor more information about the different commands, execute the JAR without arguments.
In addition to the Python standard library and Robot Framework modules, the standalone JAR versions starting from 2.9.2 also contain the PyYAML dependency needed to handle yaml variable files.
If you do not want to use any automatic way of installing Robot Framework, you can always install it manually following these steps:
- Get the source code. All the code is in a directory (a package in Python) called robot. If you have a source distribution or a version control checkout, you can find it from the src directory, but you can also get it from an earlier installation.
- Copy the source code where you want to.
- Decide how to run tests.
After a successful installation, you should be able to execute the created
runner scripts with --version option and get both Robot Framework
and interpreter versions as a result:
$ robot --version
Robot Framework 3.0 (Python 2.7.10 on linux2)
$ rebot --version
Rebot 3.0 (Python 2.7.10 on linux2)If running the runner scripts fails with a message saying that the command is not found or recognized, a good first step is double-checking the PATH configuration. If that does not help, it is a good idea to re-read relevant sections from these instructions before searching help from the Internet or as asking help on robotframework-users mailing list or elsewhere.
When an automatic installer is used, Robot Framework source code is copied into a directory containing external Python modules. On UNIX-like operating systems where Python is pre-installed the location of this directory varies. If you have installed the interpreter yourself, it is normally Lib/site-packages under the interpreter installation directory, for example, C:\Python27\Lib\site-packages. The actual Robot Framework code is in a directory named robot.
Robot Framework runner scripts are created and copied into another platform-specific location. When using Python on UNIX-like systems, they normally go to /usr/bin or /usr/local/bin. On Windows and with Jython and IronPython, the scripts are typically either in Scripts or bin directory under the interpreter installation directory.
The easiest way to uninstall Robot Framework is using pip:
pip uninstall robotframeworkA nice feature in pip is that it can uninstall packages even if they are installed from the source. If you do not have pip available or have done a manual installation to a custom location, you need to find where files are installed and remove them manually.
If you have set PATH or configured the environment otherwise, you need to undo those changes separately.
If you are using pip, upgrading to a new version requires either specifying
the version explicitly or using the --upgrade option. If upgrading
to a preview release, --pre option is needed as well.
# Upgrade to the latest stable version. This is the most common method.
pip install --upgrade robotframework
# Upgrade to the latest version even if it would be a preview release.
pip install --upgrade --pre robotframework
# Upgrade to the specified version.
pip install robotframework==2.9.2When using pip, it automatically uninstalls previous versions before installation. If you are installing from source, it should be safe to just install over an existing installation. If you encounter problems, uninstallation before installation may help.
When upgrading Robot Framework, there is always a change that the new version contains backwards incompatible changes affecting existing tests or test infrastructure. Such changes are very rare in minor versions like 2.8.7 or 2.9.2, but more common in major versions like 2.9 and 3.0. Backwards incompatible changes and deprecated features are explained in the release notes, and it is a good idea to study them especially when upgrading to a new major version.
Starting from Robot Framework 3.0, tests are executed using the robot
script and results post-processed with the rebot script:
robot tests.robot
rebot output.xmlBoth of these scripts are installed as part of the normal installation and can be executed directly from the command line if PATH is set correctly. They are implemented using Python except on Windows where they are batch files.
Older Robot Framework versions do not have the robot script and the
rebot script is installed only with Python. Instead they have interpreter
specific scripts pybot, jybot and ipybot for test execution and
jyrebot and ipyrebot for post-processing outputs. These scripts still
work, but they will be deprecated and removed in the future.
An alternative way to run tests is executing the installed robot module
or its sub module robot.run directly using Python's -m command line
option. This is especially useful if Robot Framework is used with multiple
Python versions:
python -m robot tests.robot
python3 -m robot.run tests.robot
jython -m robot tests.robot
/opt/jython/jython -m robot tests.robotThe support for python -m robot approach is a new feature in Robot
Framework 3.0, but the older versions support python -m robot.run.
The latter must also be used with Python 2.6.
Post-processing outputs using the same approach works too, but the module to
execute is robot.rebot:
python -m robot.rebot output.xmlIf you know where Robot Framework is installed, you can also execute the installed robot directory or the run.py file inside it directly:
python path/to/robot/ tests.robot
jython path/to/robot/run.py tests.robotRunning the directory is a new feature in Robot Framework 3.0, but the older versions support running the robot/run.py file.
Post-processing outputs using the robot/rebot.py file works the same way too:
python path/to/robot/rebot.py output.xmlExecuting Robot Framework this way is especially handy if you have done a manual installation.
Python virtual environments allow Python packages to be installed in an isolated location for a particular system or application, rather than installing all packages into the same global location. Virtual environments can be created using the virtualenv tool or, starting from Python 3.3, using the standard venv module.
Robot Framework in general works fine with virtual environments. The only
problem is that when using pip on Windows, robot.bat and rebot.bat
scripts are not recreated by default. This means that if Robot Framework is
installed into multiple virtual environments, the robot.bat and
rebot.bat scripts in the latter ones refer to the Python installation
in the first virtual environment. A workaround is using the --no-cache-dir
option when installing. Alternatively the start-up scripts can be ignored
and python -m robot and python -m robot.rebot commands used instead.