# ThinkDSP: Allen Downey's Python-First Introduction to Digital Signal Processing

> ThinkDSP is a free book plus a small Python package for learning DSP by writing code rather than deriving phasors. It is a teaching project, not a production signal-processing library, and the repository splits into two GitHub homes you need to choose between.

**AllenDowney/ThinkDSP** — Think DSP: Digital Signal Processing in Python, by Allen B. Downey.

- Repository: https://github.com/AllenDowney/ThinkDSP
- Website: https://allendowney.github.io/ThinkDSP/
- Stars: 4,647 · Forks: 3,596
- Language: Jupyter Notebook
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/allendowney-thinkdsp

## Why ThinkDSP teaches DSP top-down instead of starting with phasors

The README states the premise plainly: if you know how to program, you can use that skill to learn other things. Downey's complaint is that conventional DSP teaching is bottom-up, opening with mathematical abstractions like phasors and only later letting you touch a signal. ThinkDSP inverts that order. The README claims that by the end of chapter 1 you can decompose a sound into its harmonics, modify those harmonics, and generate new sounds.

That promise sets the audience. This is for a working programmer who wants to understand what a spectrum is, what a filter does to a waveform, and how sampling and aliasing interact, without first working through a semester of transform theory. It is not for someone who already writes DSP kernels and wants an optimized library. The code exists to make concepts visible, and the book is the product. The package is the supporting apparatus.

The repository is explicit that there are two GitHub homes, and picking the wrong one wastes time. ThinkDSP (this repository) holds the LaTeX source for the published first edition, the source for the think-dsp package, and two notebooks per chapter, one with examples and exercises and one with solutions. ThinkDSP2 is a draft second edition with one notebook per chapter and HTML built with Jupyter Book. The README's own guidance: if you own the published first edition and want supporting materials, you want this repository; if you are starting fresh and want the most current version, you might want ThinkDSP2.

## How the think-dsp package, notebooks and data directory fit together

The layout is a book repository with a Python package bolted on. Top-level entries include book/, nb/, soln/, data/, figs/, examples/, tests/, split/, and thinkdsp/. The nb/ directory holds the chapter notebooks, soln/ holds the solution notebooks, and examples/ holds standalone notebooks such as cacophony.ipynb, dft_example.ipynb, phase.ipynb, saxophone.ipynb and voss.ipynb. The data/ directory supplies the audio and signal files the notebooks load.

The package itself is small and declared in pyproject.toml as think-dsp version 0.2.1, described as DSP utilities from the Think DSP book, with packages = [{ include = "thinkdsp" }]. Its runtime dependencies are numpy (>=1.22.4,<3.0), scipy (>=1.13.0,<2.0) and matplotlib (>=3.8.0,<4.0). Jupyter, pandas and seaborn are optional and grouped under a notebooks extra. Python support is >=3.9,<4.0.

That dependency list tells you what kind of code this is. NumPy and SciPy do the numeric work; matplotlib renders the plots that make the concepts legible; the thinkdsp module provides the vocabulary (signals, waves, spectra) that the chapters build on. There is no compiled extension, no streaming architecture, and no device I/O layer. The repository also ships environment.yml, environment-dev.yml, requirements.txt, requirements-dev.txt and a Makefile, which together describe the intended workflow: a conda environment named ThinkDSP, notebooks opened against it, tests run with pytest from the tests/ directory.

## Installing think-dsp and running your first spectrum

The README gives three routes: Google Colab, Conda, and Poetry. It calls Colab the best quick start because it needs no local install and runs in a browser. If you want a local setup, the README says to download the repository first. Git users can shallow-clone it:

```bash
git clone --depth 1 https://github.com/AllenDowney/ThinkDSP.git
```

That leaves you with a directory called ThinkDSP. The README then recommends installing Anaconda if you do not already have Jupyter, describing it as a Python distribution containing everything needed to run the code, with user-level installs on Windows, Mac and Linux.

The repository's Makefile wraps the conda workflow. Its help target lists the available commands, and create_environment builds the environment from environment.yml:

```bash
make create_environment
conda activate ThinkDSP
```

The Makefile prints that activation hint itself. For development work there is create_environment_dev, which creates the base environment and then updates it from environment-dev.yml, giving you an editable install of the local package. Its own output notes that CI instead uses pip install -r requirements-dev.txt.

If you prefer Poetry, pyproject.toml declares the package and a notebooks extra. The extras block lists jupyter, pandas and seaborn, so a Poetry install with that extra pulls the notebook stack. Whichever route you take, the first real use is a chapter notebook rather than an import. The README links chap01.ipynb through Colab, and that notebook is where the harmonics example from chapter 1 lives. Open it, run the cells in order, and the plots appear inline. The README also warns that a few people had problems running the code in Spyder and that it is not recommended.

## Where ThinkDSP stops being the right tool

The package is classified Development Status :: 3 - Alpha in pyproject.toml. That is the author's own label, and it should shape how you treat the code. Alpha here means the API is a teaching aid, not a stability contract. If you build a pipeline on thinkdsp and the book's second edition reorganizes the module, your code follows the book, not the other way around.

The scope is narrower than the name suggests. The description is DSP utilities from the Think DSP book. There is no real-time audio path, no device abstraction, no filter-design suite, and no streaming FFT. A production audio product needs block processing, latency control, and buffer management that this repository does not attempt. Using it as the signal layer of a live application would mean writing all of that yourself, at which point SciPy is doing the work anyway and thinkdsp is a thin naming layer on top.

There is also a version trap. Two repositories carry the same book. The README says this one is the home of the PDF and EPUB of the first edition and of the frozen HTML build on Green Tea Press, while the HTML to read is the ThinkDSP2 draft. A reader who follows a first-edition chapter number into the second-edition draft, or the reverse, will find the material reorganized. The README does not document a migration path between the two, so the choice is a commitment rather than a switch. And the README does not document rollback for the conda environment, though the Makefile's delete_environment target removes it by name.

## ThinkDSP compared with reaching for SciPy directly

The honest alternative is SciPy on its own, or a general Python DSP stack built on NumPy. ThinkDSP's runtime dependencies already include SciPy, so the difference is not capability but framing. SciPy gives you functions: an FFT here, a filter design call there, each with a signature and a docstring. ThinkDSP gives you a narrative in which those functions appear at the moment a concept needs them, wrapped in objects the chapters explain.

If your goal is to ship a resampler, SciPy's documentation and its own tutorials are the shorter path. There is no book to read and no chapter ordering to respect. If your goal is to understand why the resampler behaves the way it does, the ordering is the point. Downey's argument in the README is that presenting the most important ideas first, rather than building up from abstractions, is what makes the material stick for someone who already programs.

A second alternative is a dedicated audio DSP library with a production posture. That trade is the reverse: you get a maintained API and real-time primitives, and you give up the guided path through the theory. ThinkDSP's own README does not claim to compete on that axis, and the Alpha classifier is consistent with that reading. The practical consequence is that ThinkDSP and SciPy are complements more than rivals; one is a curriculum, the other is a dependency of that curriculum.

## Licence, maintenance and what an upgrade actually costs

The code is MIT, declared in pyproject.toml with the classifier License :: OSI Approved :: MIT License. The book text is a separate matter. The README states that Think DSP is a Free Book available under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International, which permits copying, distribution and modification with attribution and without commercial use. That split matters if you plan to reuse material: the thinkdsp package and the prose carry different terms, and the non-commercial clause applies to the book, not to the MIT-licensed code. This is a description of what the repository declares, not legal advice; read both licence files before reuse.

The last push to this repository was on 2026-08-17, so the project is not dormant. There are no retrieved releases, so upgrades arrive through the repository rather than a changelog you can scan. The Makefile provides the maintenance path: update_environment runs mamba env update against environment.yml with --prune, and update_environment_dev does the same for the development environment. The --prune flag removes packages no longer listed, which is the behaviour you want when the dependency set shrinks and the behaviour you must be ready for when it does. The lint target runs flake8 and black --check, and format runs black, with a configured line length of 88 in pyproject.toml. Tests run through pytest with testpaths set to tests/ and pythonpath set to the repository root, so the suite imports the local package rather than an installed copy.

## Conclusion

Adopt ThinkDSP if you already program and want to reach spectral analysis by writing code, starting with the chap01.ipynb notebook on Colab before installing anything. Skip it if you need a maintained DSP toolkit for production audio, since the package is classified Development Status 3 - Alpha in pyproject.toml. Before committing to the book, verify which repository matches your edition: this one carries the first edition source and the think-dsp package, while ThinkDSP2 holds the second edition draft. Then run the tests target from the Makefile to confirm the package imports against your Python version.

## FAQ

### How do I install thinkdsp?

The README lists three routes: run the notebooks on Google Colab with no install, create a Conda environment, or use Poetry. For Conda, the Makefile's create_environment target builds the environment from environment.yml, and the package itself is declared in pyproject.toml as think-dsp.

### Is ThinkDSP hard to learn?

The README's premise is that programming skill substitutes for mathematical background, and it claims you can decompose a sound into harmonics, modify them and generate new sounds by the end of chapter 1. The material is ordered top-down specifically to avoid starting with abstractions like phasors.

### Which ThinkDSP repository should I use, ThinkDSP or ThinkDSP2?

The README says this repository holds the first edition's LaTeX source, the think-dsp package, and two notebooks per chapter, while ThinkDSP2 is a draft second edition with one notebook per chapter. It advises readers who own the published first edition to use this one, and readers starting fresh who want the most current version to consider ThinkDSP2.

### Can I run ThinkDSP without installing anything locally?

Yes. The README lists Google Colab first among the options and calls it the best quick start because it needs no local install, works in a browser, and is free. It provides Colab links for every chapter notebook, including the example and solution versions.

### What Python and library versions does ThinkDSP require?

pyproject.toml specifies Python >=3.9,<4.0, numpy >=1.22.4,<3.0, scipy >=1.13.0,<2.0 and matplotlib >=3.8.0,<4.0, with jupyter, pandas and seaborn as an optional notebooks extra.

## Sources

- [AllenDowney/ThinkDSP on GitHub](https://github.com/AllenDowney/ThinkDSP)
- [Issues](https://github.com/AllenDowney/ThinkDSP/issues)
- [License: MIT](https://github.com/AllenDowney/ThinkDSP/blob/master/LICENSE)
- [Project website](https://allendowney.github.io/ThinkDSP/)
- [README](https://github.com/AllenDowney/ThinkDSP/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/allendowney-thinkdsp