aima-python: Python Code for Artificial Intelligence: A Modern Approach (4th Ed.)

What the Repository Is and Who It Is For

aima-python provides Python implementations of the algorithms described in Artificial Intelligence: A Modern Approach by Stuart Russell and Peter Norvig. The textbook is a standard reference for AI courses at universities worldwide, and this repository is the companion that lets readers run the pseudocode from the book directly in Python.

The intended audience is students taking an AI course based on AIMA and instructors who want to demonstrate algorithms interactively in Jupyter notebooks. The code is organized to match the textbook's chapter structure, so a reader working through Chapter 3 on search will find the relevant algorithms in aima/search.py and the explanatory notebook at notebooks/search.ipynb or in a per-chapter folder.

The 4th edition is now canonical. The project has converged on a single version per module with no parallel 3e/4e splits. All new algorithms follow 4th-edition numbering and content. The old pairs of *3e.py and *4e.py files have been merged.

Repository Structure: Modules, Notebooks, Tests, and Lite

The repository is organized into four main areas. The aima/ directory is the importable Python package, with one module per major topic: aima/search.py for search algorithms, aima/logic.py for propositional and first-order logic, aima/planning.py for classical planning, and so on. Each module contains the implementations of the pseudocode algorithms and their support functions, classes, and data.

The notebooks/ directory holds Jupyter notebooks that explain and demonstrate the code. Each notebook corresponds to a topic (notebooks/search.ipynb) or a chapter (notebooks/chapter03/ for example). Every notebook begins with a %run bootstrap.ipynb cell that puts the repository root on sys.path, so imports like from aima import search or from aima.search import astar_search work regardless of where the notebook is launched. A GitHub Action (notebooks-to-py.yml) keeps a readable .py mirror of every notebook beside it, generated with jupytext; the .ipynb is the source of truth, not the .py mirror.

The tests/ directory is a lightweight test suite that uses assert statements and runs with pytest. The lite/ directory is a JupyterLite proof-of-concept that runs a subset of notebooks entirely in the browser via Pyodide, requiring no local installation.

Datasets live in a git submodule called aima-data, which is a separate repository. The submodule must be initialized separately after cloning; the main repository does not contain the data files.

Installing and Running the Code

Clone the repository first:

git clone https://github.com/aimacode/aima-python.git

Then install the Python dependencies:

cd aima-python
pip install -r requirements.txt

Fetch the datasets from the aima-data submodule:

git submodule init
git submodule update

The submodule download may take several minutes. Once complete, install pytest and run the test suite to confirm everything works:

pip install pytest

Then run: py.test

To install the package in editable mode so the aima package is importable from anywhere: pip install -e .

Several notebooks require the Graphviz system binary (dot) for rendering graphs. The graphviz PyPI package is only a Python wrapper; the binary must be installed separately with your OS package manager (for example apt install graphviz on Debian-based Linux, or brew install graphviz on macOS). Without it, those specific notebooks will fail at the rendering step but the rest of the code will work.

Python Version and Dependency Constraints

The codebase requires Python 3.9 or higher. It does not run on Python 2. Continuous integration tests the full suite on Python 3.9, 3.10, 3.11, and 3.12. The optional deep-learning dependencies, specifically tensorflow, keras, and opencv-contrib-python, do not yet ship binary wheels for Python 3.13 or later. The README recommends using one of the 3.9-to-3.12 versions for running everything, including those modules.

The requirements.txt file includes: cvxopt, graphviz, ipython, ipythonblocks, ipywidgets, jupyter, keras, matplotlib, networkx, numpy, opencv-contrib-python, pandas, pillow, pytest, pytest-cov, qpsolvers, scipy, sortedcontainers, and tensorflow. This is a substantial install. Engineers who only want the core search and logic algorithms without deep learning support can install the subset of dependencies their modules actually need, though requirements.txt lists all of them together without a documented way to split them.

The pyproject.toml sets name='aima', version='4.0.0', and requires-python='>=3.9'. The package is importable as: from aima.search import astar_search

What the Repository Covers and Where It Ends

The README describes the repository as eventually providing Python implementations for all the pseudocode algorithms in the book, plus tests and examples. As of the last push on 2026-06-30, empty implementations remain in some modules, which the README identifies as good places for contributors to start. The project explicitly invites contributions.

The coverage includes classical AI topics: search (BFS, DFS, A*, IDA*, MCTS), constraint satisfaction problems, logic (propositional, first-order), planning, probabilistic reasoning, Bayesian networks, Markov decision processes, reinforcement learning, and natural language processing. The 4th-edition additions include deep learning, game theory, multi-agent systems, and perception modules.

The repository does not cover topics that are outside the AIMA textbook. It is not a general machine learning library (there is no neural network training loop designed for production use) and it does not replicate the book's exercises or solutions. The notebook explanations follow the book's structure, not a standalone curriculum.

Alternative: scikit-learn and the Difference in Purpose

scikit-learn provides Python implementations of many machine learning algorithms that overlap with topics in AIMA (decision trees, nearest neighbors, SVMs, Naive Bayes). The key difference is purpose and API design. scikit-learn hides implementation details behind a consistent fit/predict interface designed for production use. aima-python exposes the implementation in the form described by the textbook pseudocode, because the goal is understanding, not deployment.

A student using aima-python can read aima/search.py and trace the A* implementation back to the book's Figure 3.26. A user of scikit-learn's equivalent cannot do that; the library is engineered for performance and generality. The two serve different purposes: aima-python is a teaching tool, scikit-learn is a production toolkit.

The repository is licensed under MIT. The last push was on 2026-06-30.

Editorial conclusion

aima-python is the correct choice for anyone studying or teaching from the AIMA 4th edition who wants runnable Python code beside each chapter. It is not designed as a production library; the code is structured around the textbook's pseudocode, not around a general-purpose API. Before installing, check that your Python version is between 3.9 and 3.12; the tensorflow and opencv-contrib-python dependencies do not yet ship wheels for 3.13.

Frequently asked questions

Official sources

1. aimacode/aima-python on GitHub
2. Issues
3. License: MIT
4. README