1.3 Installation instructions

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 also runs on Jython (JVM) and IronPython (.NET). Before installing the framework, an obvious precondition is installing at least one of these interpreters. Note that Python 3 is not yet supported, but there is an un-official Python 3 portavailable.

Different ways to install Robot Framework itself are listed below and explained more thoroughly in subsequent sections.

Package managers (e.g. pip)

Python package managers make installation trivial. For example, pip users just need to execute:

pip install robotframework

Using package managers adds a precondition to install the package manager itself first, though.

Installing from source

This approach works regardless the operating system and the Python interpreter used. You can get the source code either by downloading and extracting a source distribution from PyPI or by cloning the GitHub repository .

Using Windows installer

There are graphical installers for both 32 bit and 64 bit Windows systems, both available on PyPI.

Standalone JAR distribution

If running tests with Jython is enough, the easiest approach is downloading the standalone robotframework-<version>.jar from 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.

1.3.2 Preconditions

Robot Framework is supported on Python, Jython (JVM) and IronPython (.NET) and runs also on PyPy. The interpreter you want to use should be installed before installing the framework.

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 installation

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 currently supports Python versions 2.5, 2.6, and 2.7. The plan is to support also Python 3 in the future, and Python 2.5 support will be dropped latest then. If you need Python 3 support earlier, you can use the un-official Python 3 port. If you need to use really old Python versions, Robot Framework 2.0 and 2.1 support Python 2.3 and 2.4.

On Windows it is recommended to install Python to all users and to run the installer as an administrator. Additionally, environment variable PYTHONCASEOK must not be set.

After installing Python, you probably still want to configure PATH to make the pybot runner script executable on the command prompt.

Jython installation

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 implementations is out of the scope of these instructions, but you can find more information from http://java.com if needed.

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.

The minimum supported Jython version is 2.5 which requires Java 5 (a.k.a. Java 1.5) or newer. The forthcoming Jython 2.7 will require minimum Java 7, and that will also be the minimum for Robot Framework when support for Jython 2.5 is dropped in the future. Robot Framework 2.0 and 2.1 support Jython 2.2.

After installing Jython, you probably still want to configure PATH to make the jybot runner script executable on the command prompt.

IronPython installation

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.

When using IronPython, an additional dependency is installing elementtree module 1.2.7 preview release. This is required because the elementtree module distributed with IronPython is broken. You can install the package by downloading the source distribution, unzipping it, and 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 the ipybot runner script executable on the command prompt.

Configuring PATH

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. The runner scripts themselves require the matching interpreter to be in the PATH and thus the interpreter installation directory must be added there too.

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.

What directories to add to 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.5.3\bin).

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

Setting PATH on Windows

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 Start > Settings > Control Panel > System > Advanced > Environment Variables. There are User variables and System 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 PATH value, select Edit and 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 new PATH value, select New and set both the name and the value, this time without the leading semicolon.
Exit the dialog with Ok to 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 pybot 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 use the direct entry points with the interpreter of choice likeC:\Python26\python.exe -m robot.run.

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 with the PATH even if the directory path would contain spaces.

Setting PATH on UNIX-like systems

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.

Setting https_proxy

If you are planning to use pip for installation and are behind a proxy, you need to set the https_proxy environment variable. It is needed both when installing pip 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.

1.3.3 Installing Robot Framework

Package managers (e.g. pip)

The most popular 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, at least if they search packages from PyPI.

Installing pip

The hardest part of using pip is installing the tool itself, but luckily that is not too complicated either. You can find the latest installation instructions from pip project pages. Just remember that if you are behind a proxy, you need to set https_proxy environment variable before installing and using pip.

A bigger problem with pip is that at the time of this writing only Python supports it. The forthcoming Jython 2.7 ought to support it and even have it bundled in, though, but it is unclear when it will be supported by IronPython.

Another small limitation is that only Robot Framework 2.7 and newer can be installed using pip. If you need to install an older version, you must use other installation approaches.

Using pip

Once you have pip installed, using it on the command line is very easy. The most common usages are shown below and pip documentation has more information and examples.

# Install the latest version

pip install robotframework

# Upgrade to the latest version

pip install --upgrade robotframework

# Install a specific version

pip install robotframework==2.8.5 我们用2.8.7

# Uninstall

pip uninstall robotframework

Notice 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 --pre option:

# Install 2.9 beta 1

pip install robotframework==2.9b1

# Install the latest version even if it is a pre-release

pip install --pre robotframework

If you still use pip 1.3 or older and do not want to get the latest version when it is a pre-release, you need to explicitly specify which stable version you want to install.

Installing from source

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.

Getting source code

You typically get the source by downloading a source distribution package in .tar.gz format. Newer packages are available on PyPI, but Robot Framework 2.8.1 and older can be found from the old Google Code download page. 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 scripts 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.

Installation

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:

# Installing with Python. Creates pybot and rebot scripts.

python setup.py install

# Installing with Jython. Creates jybot and jyrebot scripts.

jython setup.py install

# Installing with IronPython. Creates ipybot and ipyrebot scripts.

ipy setup.py install

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

Using Windows installer

There are separate graphical installers for 32 bit and 64 bit Windows systems with names in format robotframework-<version>.win32.exe and robotframework-<version>.win-amd64.exe, respectively. Newer installers are on PyPI and Robot Framework 2.8.1 and older on the old Google Code download page. Running the installer requires double-clicking it and following the simple instructions.

Windows installers always run on Python and create the standard pybot and rebot runner scripts. Unlike the other provided installers, these installers also automatically create jybot and ipybot scripts. To be able to use the created runner scripts, both the Scripts directory containing them and the appropriate interpreters need to be in PATH.

Installing Robot Framework may require administrator privileges. In that case select Run as administrator from the context menu when starting the installer.

Standalone JAR distribution

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 normalPython 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-2.8.5.jar mytests.txt

java -jar robotframework-2.8.5.jar --variable name:value mytests.txt

If 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-2.8.5.jar rebot output.xml

java -jar robotframework-2.8.5.jar libdoc MyLibrary list

For more information about the different commands, execute the JAR without arguments.

Manual installation

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.
Create runner scripts you need or use the direct entry points with the interpreter of your choice.

Verifying installation

After a successful installation, you should be able to execute created runner scripts with --version option and get both Robot Framework and interpreter versions as a result:

$ pybot --version

Robot Framework 2.8.5 (Python 2.7.3 on linux2)

$ rebot --version

Rebot 2.8.5 (Python 2.7.3 on linux2)

$ jybot --version

Robot Framework 2.8.5 (Jython 2.5.3 on java1.7.0_60)

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.

Where files are installed

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 normallyLib/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 other interpreters, the scripts are typically either in Scripts or bin directory under the interpreter installation directory.

1.3.4 Uninstallation and upgrading

Uninstallation

How to uninstall Robot Framework depends on the original installation method. Notice that if you have set PATH or configured your environment otherwise, you need to undo these changes separately.

Uninstallation using pip

If you have pip available, uninstallation is as easy as installation:

pip uninstall robotframework

A nice pip feature is that it can uninstall packages even if installation has been done using some other approach.

Uninstallation after using Windows installer

If Windows installer has been used, uninstallation can be done using Control Panel > Add/Remove Programs. Robot Framework is listed under Python applications.

Manual uninstallation

The framework can always be uninstalled manually. This requires removing the created robot directory and the runner scripts. See where files are installed section above to learn where they can be found.

Upgrading

When upgrading or downgrading Robot Framework, it is safe to install a new version over the existing when switching between two minor versions, for example, from 2.8.4 to 2.8.5. This typically works also when upgrading to a new major version, for example, from 2.8.5 to 2.9, but uninstalling the old version is always safer.

A very nice feature of pip package manager is that it automatically uninstalls old versions when upgrading. This happens both when changing to a specific version or when upgrading to the latest version:

pip install robotframework==2.7.1

pip install --upgrade robotframework

Regardless on the version and installation method, you do not need to reinstall preconditions or set PATH environment variable again.

1.3.5 Different entry points

Runner scripts

Robot Framework has different runner scripts for executing test cases and for post-processing outputs based on earlier test results. In addition to that, these scripts are different depending on the interpreter that is used:

Different runner scripts
Interpreter	Test execution	Post-processing
Python	pybot	rebot
Jython	jybot	jyrebot
IronPython	ipybot	ipyrebot

On UNIX-like operating systems such as Linux and OS X, the runner scripts are implemented using Python, and on Windows they are batch files. Regardless of the operating system, using any of these scripts requires that the appropriate interpreter is in PATH.

Direct entry points

In addition to the above runner scripts, it is possible to both run tests and post-process outputs by executing framework's entry points directly using a selected interpreter. It is possible to execute them as modules using Python's -m option and, if you know where the framework is installed, to run them as scripts. The entry points are listed on the following table using Python, and examples below illustrate using them also with other interpreters.

Direct entry points
Entry point	Run as module	Run as script
Test execution	python -m robot.run	python path/robot/run.py
Post-processing	python -m robot.rebot	python path/robot/rebot.py

# Run tests with Python by executing robot.run module.

python -m robot.run

# Run tests with Jython by running robot/run.py script.

jython path/to/robot/run.py

# Create reports/logs with IronPython by executing robot.rebot module.

ipy -m robot.rebot

# Create reports/logs with Python by running robot/rebot.py script.

python path/to/robot/rebot.py

1.3 Installation instructions