Flux Model Zoo: Pinned Julia Environments for Reading Flux Code

What the zoo is, and who it is actually for

The repository describes itself as containing "various demonstrations of the Flux machine learning library", and the README states that any of them "may freely be used as a starting point for your own models". That sentence sets the scope. This is not a package you add to a Julia environment and import. It is a set of folders, each holding a runnable script and its own dependency files.

The intended reader is someone who already knows they want to use Flux and needs to see how a particular architecture is expressed in it. The examples are grouped into vision (CNNs, generative models, a spatial transformer), text (recurrent networks, a character-level language detector, a small GPT), and games under contrib/games for reinforcement learning. There is also a small other category with things like logistic regression on Iris, an autoregressive process, and FizzBuzz, plus a tutorials folder.

If you are evaluating whether to learn Flux at all, this repository is the wrong entry point. It assumes you have Julia installed and that you can read Julia code. What it offers is worked examples with pinned dependencies, which is a narrower and more useful thing than it first appears.

The mechanism: one Julia project per model

The architectural decision that matters is that every model is its own Julia project. The README says each model comes with a project and manifest file to pin all relevant packages, and that instantiating installs "all needed packages, at the exact versions when the model was last updated".

That phrasing is the whole design. A Manifest.toml records the full resolved dependency graph, so a model written against an older Flux keeps working even after Flux changes its API. Flux has changed its training loop significantly: the README notes that Flux v0.14 is current, that v0.13 and v0.14 are marked with a sun symbol, and that models upgraded to explicit gradients (v0.13.9 or later) carry a plus sign. Explicit gradients are not a cosmetic change; code written for the older implicit-gradient style will not run unchanged against the newer versions.

The pinning is what lets the repository hold models from several Flux generations at once. It also means there is no shared environment, no common utility module, and no single command that runs everything. Each folder is an island, and that is deliberate.

Running one example: the three commands that matter

The README gives the procedure directly. Open Julia in the project folder and run:

using Pkg; Pkg.activate("."); Pkg.instantiate()

Then run the model with include("<model-to-run>.jl"), or by stepping through the script line by line. The README explicitly suggests the line-by-line route, which is the honest recommendation for a teaching repository: the value is in reading the training loop, not in the final output.

GPU support is handled inside the model code rather than through a configuration key. The README says most models have this capability by default, "pointed at by calls to gpu in the model code", and that you need CUDA installed for it to work. There is no environment variable or settings file to flip; you either have a working CUDA setup or you edit the call. Note also the contribution guideline that models should be CPU/GPU agnostic and not depend directly on GPU functionality, which tells you the gpu calls are meant to be optional.

There is a Gitpod path as well: opening the repository through Gitpod gives you an online IDE. The README is careful here, stating that free access is limited under Gitpod's pricing, that your work lives in Gitpod's cloud, and that it "isn't an officially maintained feature". Treat it as a convenience, not a supported workflow.

The version markers, and why some folders are a trap

The example list is annotated with symbols that encode maintenance state, and ignoring them is the fastest way to waste an afternoon. A sun symbol marks v0.13 and v0.14 models. A cloud symbol marks v0.11 models. A snowflake marks much older ones: the meta-learning contribution is listed at v0.7 and the speech recognition example at v0.6.

Those v0.11 entries include the Seq2Seq phoneme model on CMUDict, the recursive net on the IMDB sentiment treebank, the bitstring parity challenge, the low-level-API MLP on housing data, and the DataLoader tutorial. The README explains how to run them: Flux v0.11 can be installed and run on Julia 1.6, the LTS version, and Flux v0.12 works on Julia 1.8. So a v0.11 example is not broken, but it is a different toolchain from the v0.13 and v0.14 models, and you cannot mix them in one environment without resolving the conflict yourself.

My view is that the v0.6 and v0.7 entries are effectively archival. They are pinned so they still resolve, but nothing in the README suggests they are being brought forward, and the contribution guidance frames updating old examples as a task for contributors rather than a commitment from maintainers.

What the repository does not give you

There are no releases listed for this repository, and the README does not present the examples as producing reproducible benchmark results. The contribution guidelines ask that a model README explain "what results it achieves (if applicable)", and the "if applicable" is doing real work there. Do not read this repository as a source of accuracy numbers you can cite or compare across architectures.

Licensing is the other unresolved item. The repository metadata reports the licence as NOASSERTION, which means the licence could not be identified automatically. The README says the models "may freely be used as a starting point for your own models", but that is a sentence in a readme, not a licence file with clear terms. If you intend to ship code derived from a specific folder, check that folder and the repository root for an actual licence file before you rely on the readme sentence. I am not giving legal advice here; I am pointing out that the machine-readable licence field is empty and the prose is not a substitute.

The dependency pinning is also a cost, not only a benefit. A model pinned to an old Flux will not benefit from fixes in newer Flux, and upgrading it means reading the Flux NEWS page, which the README links, plus the release pages for MLUtils and MLDatasets. The README frames this positively, saying that bringing examples up to date "is a great way to learn", which is true and also an admission that the work is left to whoever wants the newer version.

Where to look instead, and how the approach differs

The README points to MLJFlux, a bridge between Flux and MLJ.jl, described as a package for mostly non-neural-network machine learning. Its examples (Iris, Boston, MNIST) also ship with local Project and Manifest files, and they are listed at v0.11.

The difference in approach is structural. Model-zoo examples are standalone scripts: you instantiate an environment, include a .jl file, and the training loop is yours to read and modify. MLJFlux examples sit inside a modelling framework where the neural network is one model type among many, and you interact with it through MLJ's fit and predict interface. If you want to compare a neural network against a random forest on the same data with the same resampling code, the MLJFlux route fits that shape. If you want to see exactly how a diffusion model's loss is computed in Flux, the model-zoo folder is the more direct read, because there is no framework layer between you and the code.

The trade-off is that the framework buys you uniformity and costs you visibility into the Flux API being demonstrated. The contribution guidelines for model-zoo ask authors to name the Flux API a model demonstrates, including custom layers and custom operations, which is a level of detail a framework wrapper tends to hide.

Maintenance, upgrades, and the cost of pinning

The maintenance model here is distributed. The README states that each example lists the version of Flux for which it was most recently updated, and that updating them is welcome. There is no release cadence and no versioned artifact, so the state of a given folder is whatever the last commit to it left behind. The last push to the repository is recent, but that says nothing about any individual model, and you should not infer freshness of a folder from the freshness of the repository.

Upgrading a model means three things in practice: changing the Flux version in its Project.toml, re-resolving the Manifest, and then fixing whatever the API change broke. The README names the sources for that work: the Flux NEWS page, and the release pages for MLUtils and MLDatasets. The explicit-gradient migration is the largest of these jumps, and the plus sign in the example list tells you which models have already made it.

If you copy a model into your own project, you inherit the pinning decision. Keeping the old Manifest means keeping the old Flux and its constraints on the rest of your dependencies. Dropping the Manifest means you are now on the latest Flux and responsible for the migration yourself. Neither is wrong, but the repository does not make the choice for you, and the readme's framing of updates as a learning exercise is the closest it comes to acknowledging the effort involved.

Editorial conclusion

Adopt model-zoo if you are learning Flux or need a working reference for a specific architecture, and start with a model marked v0.13 or v0.14 rather than one of the v0.11 entries. Do not adopt it as a maintained library or as a source of reproducible benchmark results; the README presents the examples as starting points, and there are no releases. Before you build on any folder, check its Project.toml and Manifest.toml, read the model README for the Flux version it targets, and confirm the Julia version it needs, since the README ties Flux v0.11 to Julia 1.6 LTS and Flux v0.12 to Julia 1.8.

Official sources

1. FluxML/model-zoo on GitHub
2. Issues
3. Project website
4. README