A Minecraft mod manager for the terminal.
Go to file
Emma Tebibyte 132d82680b Merge pull request 'Fix error when no facets are specifed' (#16) from BlankParenthesis/hopper:fix-filter into main
Reviewed-on: #16
2022-12-24 04:06:21 +00:00
.github Update FUNDING.yml to include Open Collective 2021-12-08 11:10:33 -05:00
src Merge pull request 'Fix error when no facets are specifed' (#16) from BlankParenthesis/hopper:fix-filter into main 2022-12-24 04:06:21 +00:00
.gitignore Initial commit 2021-11-20 10:00:38 -07:00
Cargo.lock Changed out StructOpt for Clap 2022-09-06 23:12:00 +02:00
Cargo.toml Changed out StructOpt for Clap 2022-09-06 23:12:00 +02:00
LICENSE Create LICENSE 2021-11-20 19:48:19 -05:00
README.md comma delineated 2022-12-08 15:06:35 -05:00


        ___---    |    ---___
     ---      ___---___      ---
    |---___---         ---___---|
    |      ---___   ___---      |
     ---___       |       ___---
            --__  -  __--
    __  __
   / / / /___  ____  ____  ___  _____
  / /_/ / __ \/ __ \/ __ \/ _ \/ ___/
 / __  / /_/ / /_/ / /_/ /  __/ /
/_/ /_/\____/ .___/ .___/\___/_/
           /_/   /_/


A Minecraft package manager for the terminal.

Hopper can automatically search, download, and update Minecraft mods, modpacks, resource packs, and plugins from Modrinth so that keeping your mods up-to-date and compatible with each other is easy. With Hopper, you won't have to manually visit CurseForge and download each mod one-by-one every time you set up a new instance, or deal with the hassle of swapping out different mod versions for hours while trying to get Minecraft to accept them all at once.

Hopper is still very early in development, but important features are coming along smoothly, and we'll have lots of progress to show off in the coming weeks. It's written in Rust and released under the AGPLv3.

We're looking for people to help contribute code and write documentation. Please reach out to us in our Discord "server" if you're interested in helping out. If you have a taste in CLI apps like Hopper, your input is especially appreciated.

Inspired by applications like paru, a feature-packed AUR helper and topgrade, a tool to upgrade everything

Donate usingLiberapay

High-level Goals


  • Small binary size
  • Minimal compile times


High Priority:

  • Modrinth package searching
  • Modrinth package installation
  • Parallel package downloading
  • Per-instance package management
  • Package updating
  • Listing installed packages

Medium Priority

  • CurseForge package searching
  • CurseForge package installation
  • A man(1) entry

Low Priority:

  • Shell autocomplete
  • Configurable search result display like Starship
  • Version-control system repository package management & compilation


  • Conflict resolution
  • Dependency resolution
  • Integration into Prism Launcher and/or theseus
  • Integration into topgrade(1)
  • Graphical frontend with notifications

Modrinth REST API docs

File Structure

├── "$XDG_CONFIG_HOME"/hopper.toml
├── "$XDG_CACHE_HOME"/hopper/
│   ├── 1.19.1/
│   │ └── fabric/
│   └── 1.18.2/
│     ├── forge/
│     └── plugin/
└── "XDG_DATA_HOME"/templates/
      └── example-template.hop -> ~/.minecraft/mods/example-template.hop

Hopfile Structure

Hopfiles will contain a Minecraft version number, a list of packages, and any references to other hopfiles on which it's based, or "templates". If a hopfile is based on other template hopfiles, it inherits the packages from them. A hopfile does not inherit the package or Minecraft version from a template.

template = "example-template"
mc-version = "1.19.2"

fabric-mod = [ "sodium", "lithium" ]
resource = "alacrity"

Hopper Configuration File Structure

Hopper's configuration will be maintained with a list of all hopfiles known to hopper. Its config file will also contain a list of mod hosting sites like Modrinth and CurseForge and a list of (remote or local) version-control repositories from which to compile mods. The latter will use a (potentially custom) build file format to be defined at a later date.

hopfiles = [

modrinth = "https://api.modrinth.com/"
curseforge = "https://api.curseforge.com/"
git = [



There are multiple types of packages hopper can manage.


  • fabric-mod
  • forge-mod
  • quilt-mod


  • bukkit-plugin
  • paper-plugin
  • purpur-plugin
  • spigot-plugin
  • sponge-plugin


  • data-pack
  • fabric-pack
  • forge-pack
  • resource-pack
  • quilt-pack

These types are specified in various hopper subcommands and in its configuration.


hopper [options...] [subcommand...]


-v, --verbose

Includes debug information in the output of hopper subcommands.


get [options...] [targets...]

Searches for packages, displays the results, and downloads any selected packages to the local cache. If multiple targets are specified, results are displayed in order of specification.


-d, --dir [directory...]

Specifies the directory to download to (default is "$XDG_CACHE_HOME"/hopper/).

-m, --mc-version [version...]

Specifies for what version of Minecraft packages are being retrieved.

-n, --no-confirm

Does not display search results and downloads exact matches to the cache. Requires --mc-version and --type be specified.

-t, --type [types...]

Specifies what types of packages are being queried.

init [options...]

Creates a hopfile in the current directory and adds it to the global known hopfiles list.


-d, --dir [directory...]

Specifies the directory in which the hopfile is being created.

-f, --hopfile [hopfiles...]

Specifies templates upon which to base the new hopfile.

-m, --mc-version [version]

Specifies for what version of Minecraft packages are being managed.

-t, --type [type...]

Specifies what type of packages will be listed in this hopfile.

install [options...] [packages...]

Adds packages to the current hopfile, symlinking them to its directory. If the package cannot be found in the package cache, hopper get is run first.


-f, --hopfile [hopfiles...]

Specifies hopfiles to which mods will be added.

list [options...]

Lists all installed packages.


-f --hopfile [hopfiles...]

Lists packages installed in a specified hopfile.

-m, --mc-version [version]

Specifies for what version of Minecraft packages are being managed.

-t, --type [types...]

List all packages of a specified type.

update [options...]

Updates installed packages and adds mods if they're missing to directories with known hopfiles.


-f, --hopfile [hopfiles...]

Updates only packages in the specified hopfile. Note that this option creates a new file and symlink as it does not update the packages for other hopfiles.

-m, --mc-version [version]

Specifies for what version of Minecraft packages are being updated.

-t, --type [types...] [packages...]

Updates only packages of a specified type. Optionally takes a list of packages as an argument.