> ## Documentation Index
> Fetch the complete documentation index at: https://flox.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Using a newer version of a package

> Override the build recipe of a package from the Flox Catalog to install a newer version that is not yet available.

The Flox Catalog tracks [nixpkgs](https://github.com/NixOS/nixpkgs), which means there can be a
short delay between an upstream release and its availability in
the catalog.
See [What is the Base Catalog?](/concepts/base-catalog) for details on how
the catalog tracks nixpkgs and how often it updates.
If you need a newer version right away, you can **override** the
existing build recipe to point at the new release, then build
and publish it so the updated version is available everywhere.

This tutorial walks through the full workflow using
[Nix expression builds](/concepts/nix-expression-builds).

## Scenario

Imagine the Flox Catalog currently provides `hello` version
2.12.1, but you need version 2.12.2.
Rather than waiting for the catalog to catch up, you'll
override the build recipe to use the newer release.

## Create an environment

Let's start by creating a fresh environment for our override:

```text theme={null}
$ mkdir hello-override && cd hello-override
$ flox init
⚡︎ Created environment 'hello-override' (aarch64-darwin)

Next:
  $ flox search <package>    <- Search for a package
  $ flox install <package>   <- Install a package into an environment
  $ flox activate            <- Enter the environment
  $ flox edit                <- Add environment variables and shell hooks
  $ flox push                <- Use the environment from other machines or
                                share it with someone on FloxHub
```

## Write the override

Create a Nix expression that takes the existing `hello` build
recipe and overrides its `version` and `src` attributes:

<Note>
  The attributes you need to override depend on how the
  package is defined in nixpkgs. Different packages may use
  different attribute names or build patterns. Check the
  [nixpkgs source](https://github.com/NixOS/nixpkgs) for the package you're modifying.
</Note>

```bash theme={null}
mkdir -p .flox/pkgs/hello
```

```nix title=".flox/pkgs/hello/default.nix" theme={null}
{ hello, fetchurl }:

hello.overrideAttrs (finalAttrs: _oldAttrs: {
  version = "2.12.2";
  src = fetchurl {
    url = "mirror://gnu/hello/hello-${finalAttrs.version}.tar.gz";
    hash = "";
  };
})
```

<Note>
  The `hash` is set to an empty string because we don't know
  the correct value yet. We'll let the build tell us in the
  next step.
</Note>

## Set up Git

Nix expression builds require that all files in `.flox/pkgs/`
are tracked by Git.
Let's initialize a repository and add our files:

```bash theme={null}
git init && git add .
```

## Get the correct hash

Run `flox build` and it will fail with the expected hash:

```text theme={null}
$ flox build
warning: found empty hash, assuming 'sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA='
Building hello-2.12.2 in Nix expression mode
...
error: hash mismatch in fixed-output derivation:
         specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
            got:    sha256-WpqZbcKSzCTc9BHO6H6S9qrluNE72caBm0x6nc4IGKs=
```

Copy the hash from the `got:` line and paste it into your
expression:

```nix title=".flox/pkgs/hello/default.nix" theme={null}
{ hello, fetchurl }:

hello.overrideAttrs (finalAttrs: _oldAttrs: {
  version = "2.12.2";
  src = fetchurl {
    url = "mirror://gnu/hello/hello-${finalAttrs.version}.tar.gz";
    hash = "sha256-WpqZbcKSzCTc9BHO6H6S9qrluNE72caBm0x6nc4IGKs=";
  };
})
```

## Build the package

Now run `flox build` again:

```text theme={null}
$ flox build
Building hello-2.12.2 in Nix expression mode
...
Completed build of hello-2.12.2 in Nix expression mode

✨ Build completed successfully. Output created: ./result-hello
```

Verify it works:

```text theme={null}
$ ./result-hello/bin/hello
Hello, world!
```

## Publish the package

The [`flox publish`](/man/flox-publish) command requires a remote and
all tracked files committed and pushed.
Let's set that up and publish:

<Warning>
  The following example uses `$PWD` as the Git remote for
  simplicity. In practice, you should use a proper remote
  repository (for example on GitHub) so that others can
  reproduce your build.
</Warning>

```text theme={null}
$ git remote add origin "$PWD"
$ git add .
$ git commit -m "Add hello override"
$ git push origin main
$ flox publish hello
Building hello-2.12.2 in Nix expression mode
Completed build of hello-2.12.2 in Nix expression mode

✔ Package published successfully.

Use 'flox install myuser/hello' to install it.
```

The `flox publish` command performs a clean build from a
temporary checkout to ensure the package is fully reproducible.
See the [publishing concept](/concepts/publishing) page for more
details.

## Install from another environment

Once published, the overridden package is available in any Flox
environment.
Let's create a new environment and install it there:

```text theme={null}
$ mkdir ~/myproject && cd ~/myproject
$ flox init
$ flox install myuser/hello
✔ 'myuser/hello' installed to environment 'myproject'
```

Verify you have the overridden version:

```text theme={null}
$ flox activate -- hello --version
hello (GNU Hello) 2.12.2
```

## Next steps

This tutorial covered the simplest override — bumping a
version number.
The [Nix expression builds](/concepts/nix-expression-builds) concept page
covers additional patterns:

* [Adding extensions](/concepts/nix-expression-builds#example-extensions-of-an-existing-package) to an existing package
* [Applying patches](/concepts/nix-expression-builds#example-patches-to-an-existing-package) to fix bugs
* [Vendoring a package](/concepts/nix-expression-builds#example-vendor-an-existing-package) for deeper modifications

For a full walkthrough of the build and publish workflow,
including manifest builds, see the
[Building and publishing packages](/tutorials/build-and-publish) tutorial.