SmolML: A Pure Python Machine Learning Library You Read Instead of Deploy
A fully functional and simple Machine Learning library made entirely from scratch with Python.
At a glance
- What is it?
- SmolML rebuilds autograd, N-dimensional arrays, neural networks, trees, SVMs and K-Means using only the Python standard library. It is a teaching codebase, not a runtime, and the README says so.
- Who is it for?
- Adopt SmolML if you are learning how autograd, N-dimensional array math or backpropagation actually work and you want to read the implementation rather than call it. Do not adopt it for anything with a latency budget, a memory ceiling or a dataset that does not fit comfortably in a toy example; the README states plainly that it is far slower and heavier than NumPy-backed libraries and should not be used in production.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 55 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap SmolML fills is pedagogical, not computational
Calling scikit-learn or PyTorch teaches you the API. It does not teach you why a gradient exists, how a softmax normalises across a batch, or what an N-dimensional array actually stores in memory. SmolML targets that second question. The README frames the goal directly: production libraries are described as fantastic tools whose "internal complexity and optimizations can sometimes obscure the fundamental principles." The project's answer is to remove the optimizations entirely and leave the principles visible. The intended reader is someone who has used a machine learning library and now wants to know what happens between a forward pass and a weight update. It is not aimed at practitioners who need a model in production by Friday, and the README says as much in its Limitations section.
Two layers: a Value autograd node and an MLArray container
The foundation sits in smolml/core. The first piece is Value, described as "a simple autograd engine that tracks operations and computes gradients automatically" (smolml/core/value.py). The second is MLArray, a custom N-dimensional array "inspired by NumPy (though simplified)" that supports the mathematical operations machine learning needs (smolml/core/ml_array.py). Everything above those two files is built on them: scalers normalise MLArray inputs, activation functions and losses operate on Values, optimizers consume the gradients the autograd tape produces. That layering is the real architecture of the project. If you want to understand SmolML, read value.py and ml_array.py first, because a bug or a simplification in either propagates into every model in the repository. The README does not document the internal representation of MLArray, so the file itself is the only specification.
The model catalogue is broad but deliberately shallow
Above the core, SmolML covers more ground than a typical teaching repository. Regression offers Linear and Polynomial models. Neural networks are described as a flexible framework for feed-forward networks, with relu, sigmoid, softmax and tanh activations, Xavier and He initializers, mse_loss, binary_cross_entropy and categorical_cross_entropy, and SGD, Adam and AdaGrad optimizers. Beyond that there are Decision Tree and Random Forest implementations for classification and regression, an SVM guide under smolml/models/svm, and KMeans clustering under smolml/models/unsupervised. Preprocessing includes StandardScaler and MinMaxScaler, and there is a tokenizer section under smolml/preprocessing/tokenizers. The breadth is the point: each algorithm is a separate walkthrough rather than a unified estimator interface. There is no Pipeline, no fit-transform contract shared across model types, and no cross-validation utility mentioned anywhere in the README. Expect to wire pieces together by hand.
Getting it running means cloning, not installing
There is no published package. The README's Getting Started section gives exactly one path: git clone https://github.com/rodmarkun/SmolML, then cd SmolML, then "Explore the code in the smolml/ directory." The import path is therefore the repository root, and the README points at smolml/core, smolml/models/regression, smolml/models/nn, smolml/models/tree, smolml/models/svm, smolml/models/unsupervised, smolml/preprocessing, smolml/preprocessing/tokenizers, smolml/preprocessing/scalers and smolml/utils as the directories to read. A tests/ folder exists, and the README notes that running it requires installing requirements.txt, which it describes as being for comparing SmolML against standard libraries such as TensorFlow and scikit-learn. That distinction matters: the requirements file is a comparison harness, not a runtime dependency of the library itself, which is consistent with the claim that SmolML uses only collections, random and math.
Pure Python is the feature and the ceiling
The README is unusually blunt about performance. MLArray is called "extremely inefficient due to being written in Python," and the Limitations section states that SmolML is "WAAAAY" slower and uses far more memory than libraries with optimized C, C++ or Fortran backends. That is not a bug to be fixed; it is the cost of the transparency the project is selling. The practical consequence is that any dataset large enough to make a NumPy-backed library interesting will make SmolML painful. The README's own guidance is small datasets and toy problems. A second, quieter limitation is that no releases are listed, so there is no version number to pin, no changelog to read, and no signal about which parts of the tree are stable. The last push recorded for the repository is 2026-07-22, but that tells you when something changed, not what changed.
Where a NumPy-backed teaching stack differs
The obvious comparison is a course built on NumPy alone: write a two-layer network, implement backprop by hand, use np.ndarray for storage. That approach gives you the same conceptual education with a mature array library underneath, so you spend your attention on gradients rather than on array indexing. SmolML inverts the trade. By implementing MLArray itself, it makes the array layer part of the curriculum, which is defensible: the README calls N-dimensional arrays "one of the most underrated skills of a ML engineer." But it also means that when a shape mismatch occurs, the bug may be in your model or in the array implementation, and you have no third-party reference to compare against. Against scikit-learn or PyTorch the difference is starker still: those libraries are designed so you never read the source, while SmolML is designed so that reading the source is the only way to use it.
Licence, maintenance and what a fork actually costs
SmolML is MIT-licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement, and it means you can lift a component into your own teaching material or fork the tree without asking. It does not mean the code is warranted; MIT ships as-is, and the README's own warning against production use is the strongest statement in the repository about fitness. Maintenance cost is the variable to watch. With no releases and no homepage, there is no upgrade path to follow: you either track main or you pin a commit hash yourself. If you fork it for a course, budget for reading the relevant guide in smolml/ before each term, because the repository, not a version number, is the source of truth.
Editorial conclusion
Adopt SmolML if you are learning how autograd, N-dimensional array math or backpropagation actually work and you want to read the implementation rather than call it. Do not adopt it for anything with a latency budget, a memory ceiling or a dataset that does not fit comfortably in a toy example; the README states plainly that it is far slower and heavier than NumPy-backed libraries and should not be used in production. Before relying on any component, open the corresponding guide under smolml/core, smolml/models or smolml/utils and confirm the implementation matches the concept you intend to teach, because the repository ships no released version and no benchmark table to check against.
Community notes