Abjad works on Unix/Linux, OSX, and Windows on Python versions 3.6+.
~$ sudo pip install abjad
We strongly encourage you to not install Abjad globally via
install, but to use a virtual environment
instead. If you’re already working in a virtual environment, simply omit
Abjad supports Python 3.6 and above.
~$ git clone https://github.com/Abjad/abjad.git ~$ cd abjad abjad$ pip install .
Once you have Abjad installed, fire up Python and import it:
~$ python Python 3.6.5 (v3.6.5:f59c0932b4, Mar 28 2018, 03:03:55) [GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import abjad >>> abjad.__version__ '3.0.0'
Abjad uses LilyPond, an open-source automated engraving engine, to produce notational output.
Abjad targets whichever is the most recent version of LilyPond. At the time of this writing, that means 2.18-stable or 2.19-development. We recommend installing directly from LilyPond’s website, rather than using whichever version of LilyPond your package manager provides, as these packages are often out-of-date.
Once you have installed LilyPond, test if LilyPond is callable from your command-line by running the following command:
~$ lilypond --version GNU LilyPond 2.19.82 Copyright (c) 1996--2015 by Han-Wen Nienhuys <email@example.com> Jan Nieuwenhuizen <firstname.lastname@example.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 command-line, you should add the location
of the LilyPond executable to your
PATH environment variable. If you are
using OSX, simply run the following line in your terminal:
You can add the above line to your
~/.profile to make the change permanent.
If you are new to working with the command-line you should use Google to get a basic introduction to navigating in the shell, editing your profile and setting environment variables. There are more tutorials than we can count!
Install Graphviz (optional)¶
Abjad uses Graphviz, an open-source graph visualization library, to create graphs of rhythm-trees and other tree structures, and to create visualizations of class hierarchies for its documentation. Graphviz is not necessary for creating notation with Abjad.
To install Graphviz on Debian and Ubuntu:
~$ sudo apt-get install graphviz
~$ brew install graphviz
~$ dot -V dot - graphviz version 2.38.0 (20140413.2041)
Install extension packages¶
Abjad’s extension packages can be installed via the following commands:
~$ pip install abjad[book] # documentation tools ~$ pip install abjad[cli] # score package command-line 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
To perform development on Abjad, run the test suite, or build Abjad’s documentation locally, clone Abjad from the Github repository and install it in edit mode with its development extras:
~$ git clone https://github.com/Abjad/abjad.git ~$ cd abjad abjad$ sudo pip install -e .[book,test] # NOTE: no spaces in the string after "install"
Installing Abjad in development mode will install the following Python package dependencies (along with their own dependencies):
- pytest, for running Abjad’s test suite
- Sphinx, for building Abjad’s documentation
- PyPDF2, for performing preprocessing on LaTeX source with Abjad’s
Some of Sphinx’s dependencies provide optional optimized Python
extensions, which must be compiled before they can be used. If your machine
does not have a C compiler available, you may see error message while the
install -e ".[development]" command runs. These warnings are harmless and will
not prevent the dependencies from being installed.
To install C compilation tools on Debian and Ubuntu:
~$ sudo apt-get install build-essential
To install C compilation tools on OSX, we recommend simply installing XCode from the Apple App Store. Alternatively, you can install via Homebrew although this may take a significant amount of time.
Building the LaTeX documentation, running the test suite, and using Abjad’s
ajv book document preprocessing tools require TeXLive.
Abjad makes use of both
pdftex for producing PDFs, and the
distributed with TeXLive.
To install TeXLive on Debian and Ubuntu:
~$ sudo apt-get install texlive-full
On OSX, we recommend installing via the MacTeX distribution.
Building Abjad’s documentation requires ImageMagick, a collection of raster image processing tools.
To install ImageMagick on Debian and Ubuntu:
~$ sudo apt-get install imagemagick
~$ brew install imagemagick
~$ convert --version Version: ImageMagick 6.9.1-6 Q16 x86_64 2015-06-22 http://www.imagemagick.org Copyright: Copyright (C) 1999-2015 ImageMagick Studio LLC License: http://www.imagemagick.org/script/license.php Features: Cipher DPC Modules Delegates (built-in): bzlib freetype jng jpeg ltdl lzma png tiff xml zlib
Abjad and IPython¶
~$ sudo pip install abjad[ipython] # NOTE: no spaces in the string after "install"
To install timidity on Debian or Ubuntu:
~$ apt-get install timidity
~$ brew install timidity
Once loaded, notation and MIDI files can be embedded in your notebook whenever you use show(…) and play(…) on valid Abjad objects.
We strongly recommend installing Abjad into a virtual environment, especially
if you intend to hack on Abjad’s own source code. Virtual environments allow
you to isolate Python packages from your systems global collection of
packages. They also allow you to install Python packages without
virtualenv package provides tools for creating Python virtual environments,
and the virtualenvwrapper package provides additional tools which make
working with virtual environments incredibly easy.
Let’s install virtualenvwrapper:
~$ sudo pip install virtualenvwrapper ...
On OSX 10.11 (El Capitan) it may be necessary to install virtualenvwrapper via alternate instructions:
~$ pip install virtualenvwrapper --ignore-installed six
See here for details.
Next, set an environment variable in your shell naming the directory you want the virtual environment files to be stored in, then create that directory if it doesn’t already exist:
~$ export WORKON_HOME=~/.virtualenvs ~$ mkdir -p $WORKON_HOME
The location your virtual environment files are stored in could be
anywhere. Because you are unlikely to need to access them directly, we
suggest the .-prepended path
With the virtual environment directory created, “source” virtualenvwrapper’s script. This script teaches your shell about how to create, activate and delete virtual environments:
~$ source `which virtualenvwrapper.sh`
Finally, you can create a virtual environment via the
This will both create the fresh environment and “activate” it. Once activated,
you can install Python packages within that environment, safe in the knowledge
that they won’t interfere with Python packages installed anywhere else on your
~$ mkvirtualenv abjad ... ~(abjad)$ pip install abjad # "(abjad)" indicates the name of the virtualenv ...
You can also deactivate the current virtual environment via the
command, or switch to a different environment via the
~(abjad)$ deactivate ~$ workon my-new-score ~(my-new-score)$
To make the virtual environment configuration sticky from terminal session to
terminal session, add the following lines to your
~/.bash_profile or similar shell configuration file:
export WORKON_HOME=$HOME/.virtualenvs source `which virtualenvwrapper.sh`
Development installation within a virtualenv¶
To recap, a complete development installation of Abjad within a virtual environment requires the following steps:
- Create and activate a new virtual environment
- Clone Abjad somewhere and
cdinto the root of the cloned repository
- Install Abjad and its development / IPython dependencies
~$ mkvirtualenv abjad ... ~(abjad)$ git clone https://github.com/Abjad/abjad.git ~(abjad)$ cd abjad abjad(abjad)$ pip install -e .[development,ipython] # NOTE: no spaces between "." and "[development,ipython]" ...
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 the basics of
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
evince and your
tiMIDIty, and so on.