Build / Installation

Note

libfranka supports Ubuntu 20.04 (focal), 22.04 (jammy), and 24.04 (noble) LTS versions. Pre-built amd64 Debian packages are available for all supported versions.

Debian Package

libfranka releases are provided as pre-built Debian packages for multiple Ubuntu LTS versions. You can find the packaged artifacts on the libfranka releases page on GitHub.

Installation Instructions

Step 1: Check your Ubuntu version

lsb_release -a

Step 2: Download and install the appropriate package

For the supported ubuntu versions, use the following pattern:

# Replace with your desired version and Ubuntu codename
VERSION=0.19.0
CODENAME=focal  # or jammy, noble

wget https://github.com/frankarobotics/libfranka/releases/download/${VERSION}/libfranka_${VERSION}_${CODENAME}_amd64.deb
sudo dpkg -i libfranka_${VERSION}_${CODENAME}_amd64.deb

Tip

This is the recommended installation method for libfranka if you do not need to modify the source code.

Verify Installation

After installation, verify that libfranka is correctly installed:

dpkg -l | grep libfranka

Inside docker container

If you prefer to build libfranka inside a Docker container, you can use the provided Docker setup. Follow building-in-docker for detailed building and installation instructions.

Plain CMake

Before you begin, check the system-requirements and install the necessary dependencies listed in installing-dependencies.

After installing the dependencies, proceed to 4. Building from Source (Advanced).

Once the build is complete, you can optionally create and install a Debian package as described in installing-debian-package.

Python Package (pip)

pylibfranka is a Python binding for libfranka that enables control of Franka Robotics robots from Python. Pre-built wheels are available on PyPI and include all necessary dependencies.

Installation

The easiest way to install pylibfranka is via pip:

pip install pylibfranka

Platform Compatibility

Ubuntu Version	Supported Python Versions
20.04 (Focal)	Python 3.9 only
22.04 (Jammy)	Python 3.9, 3.10, 3.11, 3.12
24.04 (Noble)	Python 3.9, 3.10, 3.11, 3.12

Note

Ubuntu 20.04 users must use Python 3.9 due to glibc compatibility requirements.

Verify Installation

After installation, verify that pylibfranka is correctly installed:

import pylibfranka
print(f"pylibfranka version: {pylibfranka.__version__}")

# Verify key classes are available
from pylibfranka import Robot, Gripper, Model, RobotState
print("All core classes imported successfully")

Quick Start Example

import pylibfranka

# Connect to the robot
robot = pylibfranka.Robot("172.16.0.2")
state = robot.read_once()

# Print joint positions
print(f"Joint positions: {state.q}")

For more examples, see the pylibfranka examples on GitHub.

Building Python Bindings from Source

If you need to build from source (e.g., for development or unsupported platforms), follow these instructions.

Prerequisites

Python 3.9 or newer
CMake 3.16 or newer
C++ compiler with C++17 support
Eigen3 development headers
Poco development headers

Tip

If you are using the provided devcontainer, you can skip the prerequisites installation as they are already included in the container.

Installing Prerequisites on Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y build-essential cmake libeigen3-dev libpoco-dev python3-dev

Build and Install

From the libfranka root folder, install pylibfranka using pip:

pip install .

This will build the C++ extension and install pylibfranka in your current Python environment.

For development (editable install):

pip install -e .

Inside a ROS / ROS 2 workspace

ROS 2

TODO: Add ROS 2 installation instructions

ROS Noetic

Note

While libfranka and the franka_ros packages should work on different Linux distributions, official support is currently only provided for:

Ubuntu 18.04 LTS Bionic Beaver and ROS Melodic Morenia (requires at least libfranka 0.6.0)
Ubuntu 20.04 LTS Focal Fossa and ROS Noetic Ninjemys (requires at least libfranka 0.8.0)

The following instructions are exemplary for Ubuntu 20.04 LTS system and ROS Noetic Ninjemys. They only work in the supported environments.

Building the ROS packages

After setting up ROS Noetic, create a Catkin workspace in a directory of your choice:

cd /path/to/desired/folder
mkdir -p catkin_ws/src
cd catkin_ws
source /opt/ros/noetic/setup.sh
catkin_init_workspace src

Then clone the franka_ros repository from GitHub:

git clone --recursive https://github.com/frankarobotics/franka_ros src/franka_ros

By default, this will check out the newest release of franka_ros. If you want to build a particular version of franka_ros instead, check out the corresponding Git tag:

git checkout <version>

Install any missing dependencies and build the packages:

rosdep install --from-paths src --ignore-src --rosdistro noetic -y --skip-keys libfranka
catkin_make -DCMAKE_BUILD_TYPE=Release -DFranka_DIR:PATH=/path/to/libfranka/build
source devel/setup.sh

Warning

If you also installed ros-noetic-libfranka, libfranka might be picked up from /opt/ros/noetic instead of from your custom libfranka build!

Use this Library in Other Projects

To get started with libfranka in your own CMake projects, you need a simple CMakeLists.txt and a corresponding main.cpp file.

At a minimum, your project must:

Use find_package(Franka REQUIRED) to locate the library
Link against Franka::Franka inside your target_link_libraries(...) command

Below is an example CMakeLists.txt file:

cmake_minimum_required(VERSION 3.16)
project(MyRobotProject)

# Find libfranka
find_package(Franka REQUIRED)

# Create executable
add_executable(${PROJECT_NAME} src/main.cpp)

# Link libfranka
target_link_libraries(${PROJECT_NAME} Franka::Franka)

This example uses find_package to detect libfranka and sets up an executable target that links to the library.

A matching example_main.cpp file could look like this:

#include <iostream>

#include <franka/exception.h>
#include <franka/robot.h>

int main(int argc, char** argv) {
  if (argc != 2) {
    std::cerr << "Usage: " << argv[0] << " <robot ip>" << std::endl;
    return -1;
  }

  try {
    // Connect to robot
    franka::Robot robot(argv[1]);

    // Read robot state
    franka::RobotState state = robot.readOnce();

    // Print robot information
    std::cout << "Successfully connected to robot!" << std::endl;

    // Print end-effector position
    std::cout << "End-effector position (x, y, z): " << state.O_T_EE[12] << ", " << state.O_T_EE[13]
              << ", " << state.O_T_EE[14] << std::endl;

    return 0;
  } catch (const franka::Exception& e) {
    std::cerr << "Error: " << e.what() << std::endl;
    return -1;
  }
}

To build the project:

mkdir build && cd build
cmake ..
cmake --build .

Once built, run your example:

./example_main