Luigi is a Python module that helps you build complex pipelines of batch jobs. It handles dependency resolution, workflow management, visualization etc. It also comes with Hadoop support built in.
.. figure:: https://raw.githubusercontent.com/spotify/luigi/master/doc/luigi.png :alt: Luigi Logo :align: center
.. image:: https://img.shields.io/travis/spotify/luigi/master.svg?style=flat :target: https://travis-ci.org/spotify/luigi
.. image:: https://img.shields.io/codecov/c/github/spotify/luigi/master.svg?style=flat :target: https://codecov.io/gh/spotify/luigi?branch=master
.. image:: https://landscape.io/github/spotify/luigi/master/landscape.svg?style=flat :target: https://landscape.io/github/spotify/luigi/master
.. image:: https://img.shields.io/pypi/v/luigi.svg?style=flat :target: https://pypi.python.org/pypi/luigi
.. image:: https://img.shields.io/pypi/l/luigi.svg?style=flat :target: https://pypi.python.org/pypi/luigi
Luigi is a Python (3.6, 3.7 tested) package that helps you build complex pipelines of batch jobs. It handles dependency resolution, workflow management, visualization, handling failures, command line integration, and much more.
pip install luigito install the latest stable version from
Documentation for the latest release_ is hosted on readthedocs.
pip install luigi[toml]to install Luigi with
TOML-based configs__ support.
For the bleeding edge code,
pip install git+https://github.com/spotify/luigi.git.
Bleeding edge documentation__ is also available.
The purpose of Luigi is to address all the plumbing typically associated with long-running batch processes. You want to chain many tasks, automate them, and failures will happen. These tasks can be anything, but are typically long running things like
Hadoop_ jobs, dumping data to/from databases, running machine learning algorithms, or anything else.
There are other software packages that focus on lower level aspects of data processing, like
Cascading. Luigi is not a framework to replace these. Instead it helps you stitch many tasks together, where each task can be a
Hive query, a
Hadoop job in Java, a
Spark job in Scala or Python, a Python snippet,
dumping a table_ from a database, or anything else. It's easy to build up long-running pipelines that comprise thousands of tasks and take days or weeks to complete. Luigi takes care of a lot of the workflow management so that you can focus on the tasks themselves and their dependencies.
You can build pretty much any task you want, but Luigi also comes with a toolbox of several common task templates that you use. It includes support for running
Python mapreduce jobs_ in Hadoop, as well as
Pig, jobs. It also comes with
file system abstractions for HDFS_, and local files that ensures all file system operations are atomic. This is important because it means your data pipeline will not crash in a state containing partial data.
The Luigi server comes with a web interface too, so you can search and filter among all your tasks.
.. figure:: https://raw.githubusercontent.com/spotify/luigi/master/doc/visualiserfrontpage.png :alt: Visualiser page
Just to give you an idea of what Luigi does, this is a screen shot from something we are running in production. Using Luigi's visualiser, we get a nice visual overview of the dependency graph of the workflow. Each node represents a task which has to be run. Green tasks are already completed whereas yellow tasks are yet to be run. Most of these tasks are Hadoop jobs, but there are also some things that run locally and build up data files.
.. figure:: https://raw.githubusercontent.com/spotify/luigi/master/doc/user_recs.png :alt: Dependency graph
Conceptually, Luigi is similar to
GNU Make_ where you have certain tasks and these tasks in turn may have dependencies on other tasks. There are also some similarities to
Azkaban_. One major difference is that Luigi is not just built specifically for Hadoop, and it's easy to extend it with other kinds of tasks.
Everything in Luigi is in Python. Instead of XML configuration or similar external data files, the dependency graph is specified within Python. This makes it easy to build up complex dependency graphs of tasks, where the dependencies can involve date algebra or recursive references to other versions of the same task. However, the workflow can trigger things not in Python, such as running
Pig scripts_ or
We use Luigi internally at
Spotify_ to run thousands of tasks every day, organized in complex dependency graphs. Most of these tasks are Hadoop jobs. Luigi provides an infrastructure that powers all kinds of stuff including recommendations, toplists, A/B test analysis, external reports, internal dashboards, etc.
Since Luigi is open source and without any registration walls, the exact number of Luigi users is unknown. But based on the number of unique contributors, we expect hundreds of enterprises to use it. Some users have written blog posts or held presentations about Luigi:
Mortar Data (Datadog)_
(documentation / tutorial)__
Red Hat - Marketing Operations_
Leipzig University Library_
(presentation, 2016)__ /
(presentation, 2015)_ /
(slides, 2015)_ /
(poster, 2015)_ /
(paper, 2016)_ /
Some more companies are using Luigi but haven't had a chance yet to write about it:
Dow Jones / The Wall Street Journal_
We're more than happy to have your company added here. Just send a PR on GitHub.
Mailing List_ for discussions and asking questions. (Google Groups)
Source code_ (GitHub)
Hubot Integration_ plugin for Slack, Hipchat, etc (GitHub)
Luigi was built at
Spotify, mainly by
Many other peoplehave contributed since open sourcing in late 2012.
Arash Rouhani_ is currently the chief maintainer of Luigi.