Previous topic

Building Documentation

Next topic

Using music21 with Git for Eclipse

Table Of Contents

Table Of Contents

This Page

Using music21 with SVN for Eclipse

In order to develop music21 and stay current with updates to the latest versions, it is necessary to modify code using SVN for Eclipse.


1. Installing Eclipse

First, download and install the appropriate version of Eclipse from the following url if you don’t already have it:

You may use Juno (Eclipse 4.2) if you’d like – it is just a little slower, but is the future of Eclipse. The docs below are for Eclipse 3.7, but the procedure is mostly the same for using 4.2. If you’re upgrading, you can delete your music21base project in your old version of Eclipse and then just follow the same steps below.

Installing for Windows

For Windows users, the safest bet is the 32-bit version, regardless of your system’s capabilities.

If you download the 32-bit version save the Eclipse folder within the zip file in your “Program Files (x86)” directory if there is one, or “Program Files” if there isn’t.

If you choose the 64-bit version (getting more stable) then put the folder in the “Program Files” directory even if there is an “(x86)” directory. You may need to give permission or your password to make this copy.

After you’ve put the folder, go into the folder and drag a shortcut (by holding down Alt when dragging) to Eclipse to your start menu (or know how to find it later).

If you try running Eclipse and it gives you a warning about not having Java installed, go to and download a copy there.

Installing for Mac

For Mac users, download the version that complies with your system. If in doubt, 32-bit is a safe option, as 64-bit systems are back-compatible to 32-bit programs.

For Mac users, once the .tar file has been unzipped, drag the ‘eclipse’ folder into the Applications folder in your dock (make sure to drag the folder and not just the Eclipse icon - there are libraries and other dependencies that need to be kept together).


Once done, click on the Eclipse icon in the eclipse folder, and it should load.


You’ll be prompted to select a workspace directory, which, by default is created in your documents folder. Be sure to remember where this directory is, as it is where music21 will be installed.

Installing for Unix

You’ve chosen to run Unix – you should be able to figure this out on your own. :-)

2. Installing PyDev for Eclipse

(If you’re on windows, be sure to install Python through the normal Windows installation routines, see Installing Music21 in Windows)

PyDev is a Python IDE for Eclipse, which may be used in Python, Jython, and IronPython development. Installing PyDev must be done from inside Eclipse.

First, click on “Help” in the Eclipse menu bar. Then select “Install New Software...” A new dialog box will open up.


Enter the website “” in the “Work with:” field. Do not click on “add;” rather, simply press Enter and two programs will load in the field below (PyDev and PyDev Mylyn Integration; You don’t really need the Mylyn integration – if you get an error on installing, just uncheck it.). Check both boxes and click on “Next” at the bottom of the dialog box. Accept the terms, and wait for it to install. A security warning window will open, and you will be prompted to allow the certificate for Aptana.


Check the box, click OK, and the install will continue.

After the install is finished, you will be prompted to restart Eclipse, which you should do.

(For more help, visit

3. Installing SVN connectivity via Subversive

In order for Eclipse to connect to the SVN, you will also have to install Subversive.

To install Subversive, click on “Help,” then “Install new software...” In the pull-down menu, select “Indigo.” (Or “Juno” if you are using 4.2). Or type in “” if it’s not there.


When the list of programs loads in the field below, expand “Collaboration.”


Select the four options that begin with “Subversive” and click “Next.”


Accept the terms and allow the install to finish. Afterwards, you will be prompted to restart Eclipse, which you should do.

Upon restarting, an “Install Connectors” window will open, in which you should select the “SVN Kit 1.3.5” option and click “Finish.” (Juno users can use 1.3.7; 1.7 is untested)


An “Install” window will open, outlining the packets you are installing. Click on “Next >.”


Again, you’ll be prompted to accept terms, and your software will be installed (be sure to allow the software when the security warning appears). And once again, you will be prompted to restart Eclipse.

4. Checking Out music21 with Subversion

Click on “File” from the Eclipse menu bar, and select “Import.” Expand the “SVN” option. You should probably see just one SVN folder. Expand it and choose “Project from SVN”. If you see two SVN folders, expand the one that contains “Project from SVN” and select it. Click on “Next.”


There are two ways to check out music21 – normal (read-only) access and developer (read-write) access.

Most users, even SVN users, will want to install it with Read-Only access. Thus follow these instructions. If you are part of the music21 development team, skip to 4b. Checking Out with Developer Access.

4a. Checking out with Normal access

In the “Checkout from SVN” window, enter into the “URL:” field. Select the “Use the repository URL as the label” option, and click on “Next.”


Keep the defaults as shown and click “Finish” in the window that follows.


A “Check Out As” window will appear. Keep the defaults as shown and click “Finish.”


Continue the process with 5. Creating a new PyDev Project.

4b. Checking Out with Developer Access

If you’ve been given permission to contribute directly to the music21 project via SVN, follow these steps. (Otherwise, feel free to post patches, etc. to Cuthbert’s email or to the list).

In the “Checkout from SVN” window, enter into the “URL:” field.


N.B. – this is https:// not http://

Select the “Use the repository URL as the label” option. Under “Authentication,” enter the email address of the Google account that you will be using to which commit access has been granted by the developers, and the password from googlecode. Go to and click on “ password” to find your googlecode password (it’s not your normal gmail/Google account password). See this image for details on how to get the password:


Be sure to check the “Save authentication” box if you’d like to avoid being prompted for the same info in the future (sometimes it doesn’t “stick” so you may need to input this information againthe first time you commit). Also, make sure the box next to “Validate Repository Location on Finish” is selected, and click on “Next.”


Keep the defaults as shown (your window will say “https://” not “http://”) and click “Finish” in the window that follows.


A “Check Out As” window will appear. Keep the defaults as shown and click “Finish.”


Continue the process with 5. Creating a new PyDev Project.

5. Creating a new PyDev Project

After the checkout process has completed, a dialog box will open, entitled “New Project,” asking you to “select a wizard.” Expand the “PyDev” option, and select “PyDev Project.” Click “Next.”


A new window with the heading “PyDev Project” will open. In the “Project Name” field, enter something recognizable to you that is NOT “music21.” (There will be a subdirectory under the trunk file called “music21,” and if name your trunk directory “music21,” both you and the SVN will be very confused). “music21base,” for instance, is a perfectly safe name.

5a. Configuring an interpreter

For many users, especially on Windows, you will need to click on the “Please configure an interpreter in the related preferences before proceeding” link. (If it is not there, then you can skip ahead to the “When returning to the new PyDev Project box...” paragraph)


Clicking that link will open a new dialog box entitled “Preferences.” The fastest way to detect any version of Python already installed on the system is to click “Auto Config” in the right-hand column. If it can’t be found (often on Windows), you will need to click New and find your Python installation, often “C:Python27python.exe”.


Click on “Select All” in the ensuing dialog box asking what libraries to associate with music21, and click “OK.”


5b. Configuring the Project after finding the interpreter

When returning to the new PyDev Project box, a new drop-down menu should appear under the title “Interpreter,” in which you should select “python”. In the three bubbles below that field, select “Add project directly to the PYTHONPATH?” and then click on “Finish.”

(In Eclipse 4.2/Juno, the order of the first two options is reversed, so make sure you are clicking the right one).


You don’t need to configure Password Recovery.

When prompted to open a PyDev perspective, click “Yes.”


The SVN checkout will continue (it may take 10-15 minutes and may hang at around 91% for a long time) amidst a screen such as the one shown below.


Once it is finished, files should appear in the left-hand column of Eclipse with the files of music21, with dates of updates and names of updaters next to them.


6. Checking The Install

Once you close the “Welcome” screen (click the little “X” on the tab that says “Welcome”), you’re ready to work.

In order to check that the install occurred as planned, you should open a PyDev console and attempt to import the music21 module.

Click on “Window” in the Eclipse menu bar, then select “Show View” and choose “Console.”


This will open a console window in the lower portion of the Eclipse interface. To create a Python console, find the menu bar above the console, and click on the icon all the way to the right that looks like a window with a sparkle on its upper-righthand corner. A new menu will open next to it.


Choose “PyDev Console.” A new window will open with a series of buttons. Choose the “Python console” button and click “OK.”


A new console window will open in the lower portion of the Eclipse interface and will load Python. After it loads, you will be able to type. To verify that your install occurred correctly try typing “from music21 import *.”

Errors concerning additional packages may appear; if so, refer to Extending Music21 with Additional Software to install them. Most modules in music21 will still function without them, however. If other errors persist, contact the music21 staff for assistance:

As a quick music21 demo to ensure all of the components are working properly, create a Neopolitan sixth chord in the key of A minor by typing in n6chord = roman.RomanNumeral('bII6', 'a') and press Enter. To display the pitches contained in the chord, type n6chord.pitches and press Enter. The output should be [D5, F5, B-5].

Next, create an eight-note triplet duration by typing trip = duration.Duration(0.333333333333333333). (The exact number of 3’s doesn’t matter, just type a lot of them). Music21 recognizes what kind of note typically has that duration, and prints 'Eight Triplet (0.33QL)' when you type trip.fullName and press Enter.


By the way, you’ll probably want line numbers to edit Python files properly, so go ahead and go to “Window -> Preferences” and Select “General -> Editors -> Text Editors -> Show line numbers” and make it checked. Everything else about Eclipse you can learn later, but this is very important for now.

7. Configuring the Environment

Configuring the Environment is done mostly like a normal install with one big difference noted below.

To create a user environment settings file, open the music21/ file and run it by pressing the green circle with a white arrowhead in it at the top of the Eclipse interface.


A new “Run As” window will appear in which you will be prompted to select a way to run Choose “Python Run” and click on “OK.” (You should always click this when running Python programs)


In the console, you may see errors about installing additional packages, after which you will see a message beginning with “Welcome to the music21 Configuration Assisstant.”


When asked if you would like to install music21 in the normal place for Python packages, type no and press Enter.


See Configuring Environment Settings for more information on configuring user settings. Otherwise, head to: usersGuide_00_introduction for further demos and tutorials on using music21.