Abjad helps composers build up complex pieces of music notation in an iterative and incremental way. Use Abjad to create symbolic representations of all the notes, rests, staves, tuplets, beams and slurs in any score. Because Abjad extends the Python programming language, you can use Abjad to make systematic changes to your music as you work. And because Abjad wraps the powerful LilyPond music notation package, you can use Abjad to control the typographic details of the symbols on the page.

GitHub | PyPI | Documentation | Mailing list | Issue Tracker | Travis-CI

Abjad works on Unix / Linux, OSX and Windows. Abjad requires Python 3.6 or later.

If you're new to Abjad and you want to get started right away, follow the easy install instructions. If you're a more experienced Abjad user and you want to build Abjad's documentation, run Abjad's tests or add features to Abjad, then follow the developer install instructions. Whichever install you chose, you'll first need to install LilyPond and make sure that LilyPond is callable on your commandline.

LilyPond is an open-source program that engraves music notation in an automated way. Abjad uses LilyPond to produce notational output. Because package managers sometimes provide out-of-date versions of LilyPond we recommend installing the most recent version of LilyPond directly from the LilyPond website. After you install LilyPond, check to see if LilyPond is callable from your commandline:

~$ lilypond --version

GNU LilyPond 2.19.83

Copyright (c) 1996--2015 by
  Han-Wen Nienhuys <hanwen@xs4all.nl>
  Jan Nieuwenhuizen <janneke@gnu.org>
  and others.

This program is free software.  It is covered by the GNU General Public
License and you are welcome to change it and/or distribute copies of it
under certain conditions.  Invoke as `lilypond --warranty` for more
information.

If LilyPond is not callable from your commandline, you can follow the instructions provided at http://www.lilypond.org/macos-x.html. Alternatively, add the location of the LilyPond executable to your PATH environment variable. Under OSX you can update your path like this:

export PATH="$PATH:/Applications/LilyPond.app/Contents/Resources/bin/"

NOTE: OSX users should be aware that the LilyPond development team is currently experiencing difficulties publishing LilyPond for Apple's 10.15 (Catalina) series of releases. This problem seems nearly certain to be resolved at some point. But, in the meantime, OSX users who have upgraded to 10.15 must inquire on the LilyPond user list to find an interim-compiled version of LilyPond that is not yet available on LilyPond downloads page. OSX users still using Apple's 10.14 (Mojave) series of releases will experience no problems and should download the most recent version of LilyPond from the LilyPond downloads page.

After you've installed LilyPond you can decide whether to follow Abjad easy install instructions or Abjad developer install instructions. Whichever install you chose, consider setting up Python virtual environments on your computer before you begin. Python virtual environments ease the work involved in managing the ways that different versions of Python interact with the Python packages you install on your computer. Abjad development install instructions assume you will be working in a Python virtual environment. Users following an easy install are recommended to consider installing Abjad in a Python virtual environment, too. Click here for instructions on setting up Python virtual environments on your computer.

Install Abjad like this:

~$ pip install abjad

After installation, check that Python can import Abjad:

~$ python
Python 3.7.4 (v3.7.4:e09359112e, Jul  8 2019, 14:54:52) 
[Clang 6.0 (clang-600.0.57)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import abjad
>>> abjad.__version__
'3.1'

Congratulations! Easy install is complete after you install LilyPond and Abjad. Skip section B of this document. Look over optional sections C, D and E. Then read through the tutorials and examples for ideas about where to go next.

Abjad has been actively developed for more than ten years. Follow these instructions if you want to follow the cutting-edge of Abjad development, build Abjad's documentation, run Abjad's tests or add new features to Abjad.

Before you begin:

• Make sure LilyPond is installed and callable from the commandline
• Create a Python virtual environment to install Abjad

Make sure you've created a Python virtual environment for Abjad. Make sure the virtual environment is active. Then clone Abjad from the Github repository:

~(abjad)$ git clone https://github.com/Abjad/abjad.git

Make sure you've created a Python virtual environment for Abjad. Make sure the virtual environment is active. Then change into your Abjad clone and install Abjad in edit mode with development extras:

~(abjad)$ cd abjad
abjad(abjad)$ sudo pip install -e .[development]  # NOTE: no spaces in the string after "install"

Development mode will install pytest and Sphinx on your system. Abjad uses pytest to test the Abjad codeabase. Abjad uses Sphinx to build the Abjad documentation. Some of Sphinx's dependencies provide optional Python extensions that must be compiled before they can be used. If your machine does not have a C compiler available, you may see error message while pip install -e ".[development]" runs. These warnings are harmless and will not stop installation.

Graphviz is an open-source graph visualization library. Abjad uses Graphviz to to graph treelike structures, like rhythm-trees and the inheritance relations of Abjad classes. You don't need Graphviz to create notation with Abjad. But you can install Graphviz if you want to build the most recent version of Abjad's documentation on your computer:

Install Graphviz on Debian and Ubuntu like this:

~$ sudo apt-get install graphviz

Install Graphviz on OSX via Homebrew like this:

~$ brew install graphviz

Test if Graphviz is callable from your commandline like this:

~$ dot -V
dot - graphviz version 2.40.1 (20161225.0304)

Congratulations! Developer install is complete after you install LilyPond, set up a virtual environment, and clone and install Abjad. (You may optionally have installed Graphviz to build Abjad's documentation, too.) Look through sections C, D and E of this document. Then read through Abjad's tutorials and examples for ideas about where to go next.

Abjad can be used with IPython to embed music notation, graphs and audio into an IPython notebook.

To work with Abjad in IPython, install Abjad with both its development and ipython extra dependencies:

~$ sudo pip install abjad[ipython]  # NOTE: no spaces in the string after "install"

Capturing MIDI files into an IPython notebook requires the timidity package. To install timidity on Debian or Ubuntu:

~$ apt-get install timidity

To install timidity on OSX via Homebrew:

~$ brew install timidity

Create a new IPython notebook and run the following magic command in a cell to load Abjad's IPython extension. Once loaded, notation and MIDI files can be embedded in your notebook whenever you use abjad.show() and abjad.play() on valid Abjad objects:

%load_ext abjadext.ipython

After you work with Abjad for a while you may be interested in Abjad's extension packages.

Pick the extensions you want and then install them like this:

~$ pip install abjad[cli]       # score package commandline tools 
~$ pip install abjad[ipython]   # ipython integration 
~$ pip install abjad[nauert]    # quantization tools
~$ pip install abjad[rmakers]   # rhythm-maker tools
~$ pip install abjad[tonality]  # tonal analysis tools

Abjad creates a ~/.abjad directory the first time it runs. In the ~/.abjad directory you will find an abjad.cfg file. This is the Abjad configuration file. You can use the Abjad configuration file to tell Abjad about your preferred PDF file viewer, MIDI player, LilyPond language and so on. Your configuration file will look something like this the first time you open it:

# Abjad configuration file created by Abjad on 31 January 2014 00:08:17.
# File is interpreted by ConfigObj and should follow ini syntax.

# Set to the directory where all Abjad-generated files
# (such as PDFs and LilyPond files) should be saved.
# Defaults to $HOME.abjad/output/
abjad_output_directory = /Users/username/.abjad/output

# Comma-separated list of LilyPond files that 
# Abjad will "\include" in all generated *.ly files
lilypond_includes = ,

# Language to use in all generated LilyPond files.
lilypond_language = english

# Lilypond executable path. Set to override dynamic lookup.
lilypond_path = lilypond

# MIDI player to open MIDI files.
# When unset your OS should know how to open MIDI files.
midi_player = 

# PDF viewer to open PDF files.
# When unset your OS should know how to open PDFs.
pdf_viewer = 

# Text editor to edit text files.
# When unset your OS should know how to open text files.
text_editor = 

Follow ini syntax when editing the Abjad configuration file. Background information is available at http://en.wikipedia.org/wiki/INI_file. Under MacOS you might want to set you midi_player to iTunes. Under Linux you might want to set your pdf_viewer to evince and your midi_player to tiMIDIty.