# Oceananigans.jl: Julia fluid dynamics for ocean and climate models

> Oceananigans.jl solves the nonhydrostatic and hydrostatic Boussinesq equations with finite volumes on CPUs and GPUs. It is aimed at researchers who want to write a simulation in a dozen lines of Julia, and it is flexible enough that the same interface covers simple turbulence boxes and spherical-shell ocean configurations.

**CliMA/Oceananigans.jl** — 🌊  Julia software for fast, friendly, flexible, ocean-flavored fluid dynamics on CPUs and GPUs

- Repository: https://github.com/CliMA/Oceananigans.jl
- Website: https://clima.github.io/OceananigansDocumentation/stable
- Stars: 1,429 · Forks: 300
- Language: Julia
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/clima-oceananigans-jl

## What Oceananigans.jl solves, and for whom

Oceananigans.jl is a finite volume solver for the nonhydrostatic and hydrostatic Boussinesq equations. The README states it handles incompressible fluid dynamics in Cartesian and spherical shell domains. That scope matters: this is not a general purpose CFD package for compressible flow, combustion, or arbitrary geometry. It is ocean-flavored, and the examples directory reflects that, with scripts for baroclinic adjustment, internal tides, Langmuir turbulence, a tilted bottom boundary layer, and a spherical baroclinic instability.

The audience is researchers and graduate students in physical oceanography and climate modeling who are comfortable in Julia, or willing to become so. The README describes the interface as ultra-flexible, with the goal that simple simulations stay easy while complex ones remain possible. The repository is community-driven, with contributors from academia and industry, and the README points to a jobs discussions category for developer and user opportunities. The package is registered in the Julia general registry, so installation goes through the standard package manager rather than a source build.

## How the finite volume machinery is put together

A simulation is assembled from a small number of objects. You construct a grid, then a model on that grid, then set initial conditions, then wrap the model in a Simulation with a time step and a stop time, and call run!. The README's first example does exactly this: a RectilinearGrid with size (128, 128), x and y spanning 0 to 2π, and topology (Periodic, Periodic, Flat), a NonhydrostaticModel with WENO advection, and a Simulation with Δt=0.01 and stop_time=4.

The grid carries the topology, so a Flat third dimension is how a two-dimensional configuration is expressed rather than a separate 2D code path. The model carries the physics choices, here the advection scheme. The Simulation carries the time stepping. That separation is what makes the interface flexible: swapping CPU() for GPU() is a grid argument change, not a rewrite, and the README says loading CUDA.jl via using CUDA and changing CPU() to GPU() makes the same code run on a CUDA-enabled Nvidia GPU.

Beyond the core solver, the repository layout shows benchmarking/, validation/, examples/, and ext/ directories, plus a Dockerfile that installs hdf5-tools and instantiates the project. The topics list includes data assimilation and machine learning alongside fluid dynamics, so the package is positioned as a component in larger workflows rather than only a standalone simulator.

## Installing Oceananigans.jl and running a first model

The README gives installation as a registered Julia package. You need Julia 1.10 or later. Launch Julia and add the package through Pkg, then confirm which version landed in your environment, because the README warns that Pkg.add installs the latest version compatible with your current environment.

```julia
julia> using Pkg

julia> Pkg.add("Oceananigans")

julia> Pkg.status("Oceananigans")
```

The status line is the one to read before following any tutorial, since the documentation has both a stable and a development build.

The README's first model is a two-dimensional, horizontally periodic turbulence simulation on 128² cells for 4 non-dimensional time units. Copy it as written to check that your installation works.

```julia
using Oceananigans
grid = RectilinearGrid(CPU(), size=(128, 128), x=(0, 2π), y=(0, 2π), topology=(Periodic, Periodic, Flat))
model = NonhydrostaticModel(grid; advection=WENO())
ϵ(x, y) = 2rand() - 1
set!(model, u=ϵ, v=ϵ)
simulation = Simulation(model; Δt=0.01, stop_time=4)
run!(simulation)
```

After run! returns, the model has advanced to stop_time. To move the same script to a GPU, load CUDA.jl and change the first argument of RectilinearGrid from CPU() to GPU(). The README states this is the only change required. If you prefer containers, the repository's Dockerfile builds from julia:1.10.6, installs hdf5-tools, copies the source to /Oceananigans.jl/, and runs Pkg.instantiate() followed by using Oceananigans.

## Where the package is the wrong tool

The Boussinesq approximation is baked into the model types. If your problem needs compressible dynamics, a non-Boussinesq equation set, or a free surface treated without that approximation, the model types documented here do not cover it. The domains are Cartesian and spherical shell; there is no indication of support for unstructured or body-fitted meshes, so a simulation that must conform to complex bathymetry in an arbitrary coordinate system is outside the stated scope.

The language is a second boundary. Everything in the repository is Julia, the examples are Julia scripts, and the documentation is written for Julia users. A team standardized on Python or Fortran gets no bindings from this package. The README does not document rollback procedures, nor does it describe a deprecation policy for the versioned releases, so pinning behavior across upgrades is something you would have to establish from the release notes yourself.

There is also a hardware caveat hidden in the friendly GPU story. The README's claim is specifically about CUDA-enabled Nvidia GPUs. Nothing in the README indicates support for other accelerator vendors, so the CPU() to GPU() swap should be read as an Nvidia path.

## How it differs from MITgcm and from general CFD frameworks

The closest comparison in spirit is MITgcm, the long-standing Fortran ocean model. MITgcm is built around the hydrostatic primitive equations with a strong emphasis on large-scale ocean circulation and a mature data assimilation capability, and it is configured through Fortran namelists and source edits. Oceananigans.jl instead exposes a Julia object model where the grid, model, and simulation are values you construct in a script, and it offers both nonhydrostatic and hydrostatic Boussinesq equations in the same package. The practical difference is the iteration loop: a configuration change in Oceananigans is a line of Julia, while in a namelist-driven model it is an input file plus a rebuild.

Against a general purpose CFD framework such as OpenFOAM, the difference is scope rather than ergonomics. OpenFOAM ships mesh generation, a large solver library, and a case-directory workflow aimed at arbitrary engineering geometries. Oceananigans.jl does not, and the README describes it as ocean-flavored, with Cartesian and spherical shell domains. If your geometry is a pipe, a pump, or a car body, the general framework is the right category and this package is not. If your geometry is a periodic box or a spherical shell with ocean physics, the narrower tool does less work for you to undo.

## Maintenance status, releases, and the MIT licence

The repository is not archived, and the last push was on 2026-09-10, which is recent. The release cadence visible in the published releases is brisk: v0.112.0 on 2026-09-08, v0.111.0 on 2026-08-31, and v0.110.20 on 2026-08-27. That pattern, a minor release followed by patch releases within days, suggests the API is still moving. The README's own instruction to check Pkg.status("Oceananigans") after installing is a reasonable habit to keep, because a tutorial written against one minor version may not match the next.

Upgrade cost therefore falls mainly on anyone who pins to a specific behavior. The README does not document a deprecation window or a long-term support release, so the safe approach is to record the exact version in your environment and consult the release notes before moving.

The licence is MIT, which is permissive: it allows use, modification, and redistribution with the licence text retained. The README also links a CITATION.cff file and a JOSS paper, so academic users have a citation path. Nothing here constitutes legal advice; if the licence terms matter to your organization, read LICENSE in the repository.

## Conclusion

Adopt Oceananigans.jl if your work is incompressible Boussinesq fluid dynamics in Cartesian or spherical shell domains and you are willing to write Julia, because the same script moves from CPU() to GPU() by loading CUDA.jl. Do not adopt it if you need compressible flow, unstructured meshes, or a Python-first workflow, since the package is Julia and its examples and documentation are Julia. Before committing, run the two-dimensional turbulence example from the README on your own hardware, check Pkg.status("Oceananigans") against the version the documentation describes, and read the docs page for the specific model type you plan to use.

## FAQ

### How do I install Oceananigans.jl?

Download Julia version 1.10 or later, launch it, and run Pkg.add("Oceananigans") after using Pkg. The README then suggests checking the installed version with Pkg.status("Oceananigans"), since Pkg.add installs the latest version compatible with your environment.

### Can Oceananigans.jl run on a GPU?

Yes, for CUDA-enabled Nvidia GPUs. The README states that loading CUDA.jl with using CUDA and changing CPU() to GPU() in the grid constructor makes the example code run on the GPU.

### What equations does Oceananigans.jl solve?

The README describes it as a finite volume package for the nonhydrostatic and hydrostatic Boussinesq equations, simulating incompressible fluid dynamics in Cartesian and spherical shell domains.

## Sources

- [CliMA/Oceananigans.jl on GitHub](https://github.com/CliMA/Oceananigans.jl)
- [License: MIT](https://github.com/CliMA/Oceananigans.jl/blob/main/LICENSE)
- [Project website](https://clima.github.io/OceananigansDocumentation/stable)
- [README](https://github.com/CliMA/Oceananigans.jl/blob/main/README.md)
- [Releases](https://github.com/CliMA/Oceananigans.jl/releases)

---

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