# SmolML tells you to clone it and read it, and never says how to install it

> A pure Python machine learning library written to be read: an autograd engine, a custom array type, trees, k-means, and nothing from NumPy or SciPy. The performance warning is emphatic and honest, the test suite depends on libraries the library itself does not use, and two subjects with full guides are missing from the feature list.

**rodmarkun/SmolML** — A fully functional and simple Machine Learning library made entirely from scratch with Python. 

- Repository: https://github.com/rodmarkun/SmolML
- Stars: 502 · Forks: 33
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/rodmarkun-smolml

## The getting started section is a clone command

There is no install command in the visible documentation. The recommended path is:

```bash
git clone https://github.com/rodmarkun/SmolML
cd SmolML
# Explore the code in the smolml/ directory!
```

The comment tells you what to do with the checkout, which is read it. That is consistent with the stated purpose, since the argument for this library is that you can trace an implementation from basic operations to a whole algorithm, and a wheel would defeat the point.

It is still slightly odd, because the repository is a package. The tree carries a build configuration, a packaging file and a lock file for the uv tool, and the project metadata names the package and gives it a description and a version of 0.1.0. So the machinery to install it exists and the documentation does not use it.

The second half of the getting started section is where the external dependencies appear, and the framing is precise about why. You are told to run the tests in the tests directory after installing the requirements file, and immediately qualified: that file exists for comparing SmolML against standard libraries such as TensorFlow and scikit-learn and for generating plots, and SmolML itself uses none of them.

That is an unusual admission and a useful one. The library's own test suite is differential rather than unit: it checks that this implementation produces the same answers as the libraries it is imitating.

## Two build files describe one package

The repository root has both a packaging file and a legacy setup script. The modern one declares the build backend and its minimum version, the wheel tool, the package name and version, the description and the readme reference.

The two exist for compatibility with older tooling, which is a common and harmless arrangement. The reason to mention it here is the instruction that follows: since the documentation tells you to clone rather than install, neither file is exercised by the documented workflow, so nothing in the readme would tell you if one of them had drifted out of sync with the other.

The lock file tells you the intended tool. Its presence, together with the truncated test instruction that begins with a uv pip call, says the project expects uv rather than pip for the one operation that needs external packages.

For a library whose whole argument is readability, the packaging is the least interesting part and the file tells you so by never mentioning it.

## Two guided subjects have no feature entry

The walkthrough is a list of guides, each one a readme inside a module directory, split into a recommended main order and a set of optional side paths.

The main list runs from the core, which is automatic differentiation and n-dimensional arrays, through regression, neural networks, tree models, support vector machines, k-means clustering and tokenizers. The side list covers activation functions, weight initialisers, loss functions, optimisers, memory utilities and preprocessing.

The features section is shorter than that list, and the two subjects that have guides but no feature entry are support vector machines and tokenizers.

Everything else in the main list has a matching bullet: regression covers linear and polynomial models, neural networks are described as a flexible framework for feed-forward networks, tree models cover decision trees and random forests, and k-means is there as the unsupervised clustering algorithm. Scalers appear as essential preprocessing rather than a model. So the discrepancy is two guides that the feature summary does not mention at all.

That is worth knowing if you are deciding whether a topic is covered, because the feature list is the part a skimmer reads. Both are in the main order, which suggests they are considered core material rather than extras.

## The array type is documented as extremely inefficient

The foundation is two classes, and one of them comes with its own performance warning in the documentation.

The autograd engine is described as a simple implementation that tracks operations and computes gradients automatically. That is the micrograd pattern in miniature: each node holds a value and a gradient, and a backward pass walks the graph. Nothing about it is hidden behind a framework, which is the point.

The array type is a custom n-dimensional array inspired by NumPy, though simplified, and it is described in the same sentence as extremely inefficient because it is written in Python. The documentation frames that as ideal for understanding what an n-dimensional array actually is, and calls the skill underrated.

Both are the pieces everything else is built on. The model families, the losses and the optimisers all consume them, which means a reader who understands those two files understands the interfaces the rest of the library uses.

The rest of the building blocks are named concretely, which is what makes the library useful as a reference: relu, sigmoid, softmax and tanh; Xavier and He initialisers; mean squared error, binary cross entropy and categorical cross entropy; and stochastic gradient descent with Adam and AdaGrad.

## The guides are readmes inside the source directories

There is no documentation site. Each guide in the walkthrough points at a directory inside the package, so the tutorial and the implementation are the same files, and you read them in the order the readme suggests.

The order is presented as recommended rather than required, and the reader is invited to divert when something else interests them, which is the framing of a quest list with a main path and optional side content. The main path builds up from the core arrays and gradients through the model families; the side path is the utility layer underneath them.

The method recommended for using all of it is stated in one line at the end of the approach section: read the guides, check the code, and then try to implement your own versions of the components. That last step is the point of the project, and it explains why the walkthrough is a list of directories rather than a set of exercises.

The stated philosophy underneath is that the best way to understand a complex topic is often to build it, and that production libraries are good tools whose internal complexity and optimisations can obscure the principles. The design goals are transparency, understandability and education, with one explicit priority: code written for understanding rather than peak performance.

## The limitations section names the alternatives for you

The performance section is the most direct passage in the readme, and it does not soften itself.

It says the library is built for learning and therefore should not be used in production. Being pure Python, it is described as far slower and as using a great deal more memory than libraries with optimised C, C++ or Fortran backends, with NumPy given as the example. It says the right fit is small datasets and toy problems where understanding the mechanics matters more than computation time, and it repeats the instruction not to use it for production applications.

Then it names what to use instead: battle-tested libraries including scikit-learn, PyTorch, TensorFlow and JAX.

That last step is the part that makes the section useful rather than merely cautious. A limitations section that only says do not use this for production leaves you to work out what to use; this one hands you a shortlist and frames the relationship as a comparison, which is the honest framing for a reimplementation.

Licensing is MIT, the repository is not archived, and the branch was last pushed on 2026-07-22, a little over two months before this batch was assembled. There are no releases, so version 0.1.0 in the metadata is the only version marker available.

## Conclusion

Read SmolML as a teaching codebase rather than as a dependency, and pick the two or three modules you actually want to understand rather than adopting the package. It ships an autograd engine and an array type you can read end to end, which is the argument for it, and its own documentation says plainly that it is far slower and far heavier on memory than any optimised backend. Two details to note before you read. The guided tour lives inside the source directories rather than in a documentation site, and the tests exist to compare its output against other libraries, which means running them pulls in tools the library deliberately avoids.

## FAQ

### How do I install SmolML?

The documentation does not give an install command. It tells you to clone the repository and explore the package directory, and the package does carry build configuration, but installing is not part of the documented path.

### Does SmolML use NumPy or SciPy?

No. It is built with pure Python and basic standard library modules including collections, random and math, with no NumPy, no SciPy and no compiled extensions.

### What do the SmolML tests need installed?

The requirements file used for the tests is for comparing SmolML against libraries such as TensorFlow and scikit-learn and for generating plots with matplotlib. SmolML itself does not use any of them.

### Which models does SmolML implement?

Linear and polynomial regression, a feed-forward neural network framework, decision trees and random forests, and k-means clustering. It also provides an autograd engine, a custom n-dimensional array, scalers, activation functions, initialisers, losses and the SGD, Adam and AdaGrad optimisers.

### Is SmolML suitable for production use?

No, and the documentation says so directly. Being pure Python it is much slower and uses far more memory than libraries with compiled backends, and it is intended for small datasets and teaching problems.

### Where are the SmolML guides?

Inside the source directories themselves, one readme per module, listed in a recommended order with optional side topics. The suggested method is to read the guide, check the code, and then implement your own version.

## Sources

- [Issues](https://github.com/rodmarkun/SmolML/issues)
- [License: MIT](https://github.com/rodmarkun/SmolML/blob/main/LICENSE)
- [README](https://github.com/rodmarkun/SmolML/blob/main/README.md)
- [rodmarkun/SmolML on GitHub](https://github.com/rodmarkun/SmolML)

---

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