PyTheory: Music Theory for Humans

PyPI version Supported Python versions License

PyTheory is a Python library for exploring music theory, composing multi-part arrangements, and exporting them to MIDI, sheet music, or audio — with nothing to install but Python packages. No DAW, no samples, no plugins.

New to uv? It’s the fast Python package manager — one command to install, no virtualenv ceremony.

$ uv add pytheory

Or skip installing entirely and run it in your browser.

Get started

Try the playground

Why would I want this?

Different people come to PyTheory for different reasons — pick the path that sounds like you:

Learning theory

See what’s inside a chord, why a progression works, or what makes Dorian sound different from minor — answered in code you can poke at.

Quickstart
Playing guitar

Chord fingerings, scale diagrams, Nashville number charts, and tablature — without opening a browser full of ads.

Instruments and Fingerings
Sketching songs

Hear an idea now: four chords, a drum groove, a bass line, through your speakers in a dozen lines. Export MIDI when it’s good and finish in your DAW.

Sequencing
Playing live

A MIDI keyboard and a synth rig in the terminal, with recording — or a session to join over Ableton Link.

Live Performance
Capturing ideas

You hummed a melody into your phone. Score.from_wav("hum.m4a") turns it into notes, MIDI, or sheet music.

Listening — Microphone In
Tuning up

pytheory tune --instrument guitar is a real-time strobe tuner that locks to your open strings.

Listening — Microphone In
Composing with AI

Claude Code drives PyTheory from natural language: “write me a bossa nova in G minor” becomes a Score you can hear, edit, and export.

PyTheory + Claude Code

Theory

The theory layer works everywhere Python runs — no audio setup needed. Tones, scales, chords, keys, intervals, harmony, 16 musical systems:

>>> from pytheory import Key, Chord, Tone

>>> Key("C", "major").chords
['C major', 'D minor', 'E minor', 'F major', 'G major', 'A minor', 'B diminished']

>>> [c.symbol for c in Key("G", "major").progression("I", "V", "vi", "IV")]
['G', 'D', 'Em', 'C']

>>> Tone.from_string("C4").interval_to(Tone.from_string("G4"))
'perfect 5th'

Dig deeper in Music Theory Fundamentals, or travel further afield: Indian ragas in true shruti tuning, Arabic maqams with real quarter tones, and a dozen more tunings all live in Musical Systems.

Guitar

Chord fingerings, identification, scale diagrams, and tablature — for guitar and 24 other fretted and stringed instruments, in any tuning:

>>> from pytheory import Fretboard, Chord

>>> print(Fretboard.guitar().tab("Am"))
A minor
e|--0--
B|--1--
G|--2--
D|--2--
A|--0--
E|--x--

>>> Chord.from_symbol("F#m7b5").identify()
'F# half-diminished 7th'

>>> Fretboard.guitar().chord("G")
Fingering(E=3, A=2, D=0, G=0, B=0, e=3)

Melodies render to ASCII tablature too — write a line, print the tab, hand it to a guitarist. See Instruments and Fingerings for fingerings and scale diagrams, and Nashville Numbers, Blues Scales, and Tablature for Nashville number charts, blues scales, and full-song tabs.

Composition

When you’re ready to make noise, the composition layer adds drums, synths, effects, and multi-part arrangements. Sketch an idea, hear it through your speakers, export MIDI, finish in your DAW:

from pytheory import Score, Key, Duration
from pytheory.play import play_score

score = Score("4/4", bpm=120)
score.drums("rock", repeats=8, fill="rock", fill_every=4)

piano = score.part("piano", instrument="piano", reverb=0.3)
lead = score.part("lead", synth="saw", envelope="pluck",
                  delay=0.2, reverb=0.2, lowpass=4000)
bass = score.part("bass", synth="triangle", lowpass=900)

for chord in Key("G", "major").progression("I", "V", "vi", "IV") * 2:
    piano.add(chord, Duration.WHOLE)

lead.add("D5", 1).add("B4", 0.5).add("D5", 0.5)
lead.add("G5", 1).add("E5", 1)
lead.add("D5", 0.5).add("B4", 0.5).add("A4", 1)
lead.add("G4", 2).rest(2)

for n in ["G2", "G2", "D2", "D2", "E2", "E2", "C2", "C2"] * 2:
    bass.add(n, Duration.HALF)

play_score(score)

Everything you hear is synthesized from math — 56 waveforms, 83 instrument presets, 100 drum patterns, and a full effects rack (reverb, delay, chorus, distortion, sidechain, automation). When it sounds right, take it anywhere: WAV, MIDI, ABC notation, MusicXML, LilyPond, or guitar tab. Synthesizers and Effects cover the sound design; Playback and Export covers every export format.

Or hear a randomly generated track from the command line — different every time:

$ uv run pytheory demo

Start Here

Making Music

Guitar & Strings

Theory Reference

Tools

API Reference

Project

Music is math that makes you feel something. PyTheory gives you the math. What you feel is up to you.