Check out ferium's sister projects ferinth and furse
They are Rust wrappers for the official Modrinth and CurseForge APIs respectively
Ferium is a fast and feature rich CLI program for downloading and updating Minecraft mods from Modrinth, CurseForge, and GitHub Releases, and modpacks from Modrinth and CurseForge. Simply specify the mods or modpacks you use through the CLI, and in just one command you can download all the mods or the modpack you configured.
-
Download mods from multiple sources, namely Modrinth, CurseForge, and GitHub Releases
-
Download modpacks from multiple sources, namely Modrinth and CurseForge
-
It's super fast due to multithreading for network intensive tasks
Your results may vary depending on your internet connection.
It downloads my modpack Kupfur with 79 mods in 15 seconds:
Ferium.Kupfur.Upgrade.mp4
It downloads MMTP, the largest modpack with around 400 mods, in just under a minute:
ferium_MMTP_install.mp4
-
Upgrade all your mods in one command,
ferium upgrade
- Ferium checks that the version being downloaded is the latest one compatible with the chosen mod loader and Minecraft version
- You can configure overrides for mods that are not specified as compatible but still work
-
Download and install your modpack in one command,
ferium modpack upgrade
-
Create multiple profiles and configure different mod loaders, Minecraft versions, output directories, and mods for each
Ferium builds from GitHub Releases do not require any external dependencies at runtime.
If you compile from source, using GCC to build will result in binaries that require GCC to be available at runtime.
On Linux, the regular version requires some sort of desktop environment that offers an XDG Desktop Portal.
The nogui
versions do not need this as they don't have a GUI file picker, making these variants suitable for servers.
Coming to more package managers soon™
Arch User Repository for Arch Linux
Warning
From-source builds will install the Rust toolchain and GCC
Installation method | GUI file dialogue | No GUI |
---|---|---|
Install pre-built binaries from GitHub Releases | ferium-gui-bin | ferium-bin |
Build from source at the latest tag | ferium-gui | ferium |
Build from source using the latest commit | ferium-gui-git | ferium-git |
Homebrew for macOS or Linux
brew install ferium
Scoop for Windows
scoop bucket add games
scoop install ferium
Pacstall for Ubuntu
pacstall -I ferium-bin
Nixpkgs for NixOS or Linux
Note
See package page for installation instructions
crates.io for the Rust toolchain
cargo install ferium
Warning
Remember to use an add-on like cargo-update to keep ferium updated to the latest version!
GitHub Releases for any platform
Warning
You will have to manually download and install every time there is a new update
- Download the asset suitable for your operating system from the latest release
- Unzip the file and move it to a folder in your path, e.g.
~/bin
- Remember to check the releases page for any updates!
Note
A lot of ferium's backend is in a separate project libium.
It deals with things such as the config, adding mod(pack)s, upgrading, file pickers, etc.
Ferium stores profile and modpack information in its config file. By default it is located at ~/.config/ferium/config.json
, but you can change this in 2 ways. You can set the FERIUM_CONFIG_FILE
environment variable or set the --config-file
global command flag, the flag always takes precedence.
You can also set a custom CurseForge API key or GitHub personal access token using the CURSEFORGE_API_KEY
and GITHUB_TOKEN
environment variables or the --curseforge_api_key
and --github-token
flags respectively. Again, the flags take precedence.
You can either have your own set of mods in what is called a 'profile', or install a modpack.
- Create a new profile by running
ferium profile create
and entering the details for your profile- Then, add your mods using
ferium add
- Finally, download your mods using
ferium upgrade
- Then, add your mods using
- Add a modpack by running
ferium modpack add <project_id>
- After which, run
ferium modpack upgrade
to download and install the modpack
- After which, run
- Modrinth
ferium add project_id
- Where
project_id
is the slug or project id of the mod- For example, Sodium has the slug
sodium
and a project idAANobbMI
- You can find the slug in the website url (
modrinth.com/mod/<slug>
), and the project id at the bottom of the left sidebar under 'Technical information'
- For example, Sodium has the slug
- So to add Sodium, you should run
ferium add sodium
orferium add AANobbMI
- CurseForge
- GitHub
ferium add owner/name
- Where
owner
is the username of the owner of the repository andname
is the name of the repository (both case-insensitive)- For example Sodium's repository has the id
CaffeineMC/sodium-fabric
- You can find these at the top left part of the repository's page as a big 'owner / name'
- For example Sodium's repository has the id
- So to add Sodium, you should run
ferium add CaffeineMC/sodium-fabric
(again, case-insensitive) - Note: The GitHub repository has to release JAR files in their Releases for ferium to download, or else it will refuse to be added
If you want to use files that are not downloadable by ferium, place them in the user
folder in the output directory. Files here will be copied to the output directory when upgrading.
Warning
Profiles with the Quilt mod loader selected will not copy theiruser
mods, this is because Quilt loads mods from nested directories as well (for loader versions above0.18.1-beta.3
)
- Modrinth Modpacks
ferium modpack add project_id
- Where
project_id
is the slug or project id of the modpack- For example, Better Minecraft has the slug
better-minecraft
and a project idshFhR8Vx
- You can find the slug in the website url (
modrinth.com/modpack/<slug>
), and the project id at the bottom of the left sidebar under 'Technical information'
- For example, Better Minecraft has the slug
- So to add Better Minecraft, you should run
ferium modpack add better-minecraft
orferium modpack add shFhR8Vx
- CurseForge Mods
Note
If your output directory is not empty when setting it, ferium will offer to create a backup. Please do so if it contains any files you would like to keep
Now after adding all your mods, run ferium upgrade
to download all of them to your output directory.
This defaults to .minecraft/mods
, where .minecraft
is the default Minecraft resources directory. You don't need to worry about this if you play with Mojang's launcher (unless you changed the resources directory).
You can choose to pick a custom output directory during profile creation or change it later.
If ferium fails to download a mod, it will print its name in red and give the reason. It will continue downloading the rest of the mods and will exit with an error.
Warning
When upgrading, any files not downloaded by ferium will be moved to the.old
folder in the output directory
Note
If your output directory'smods
andresourcepacks
are not empty when setting it, ferium will offer to create a backup. Please do so if it contains any files you would like to keep
Now after adding all your mods, run ferium modpack upgrade
to download the modpack to your output directory.
This defaults to .minecraft
, which is the default Minecraft resources directory. You don't need to worry about this if you play with Mojang's launcher (unless you changed the resources directory).
You can choose to pick a custom output directory when adding modpacks or change it later.
If ferium fails to download a mod, it will print its name in red and give the reason. It will continue downloading the rest of the mods and will exit with an error.
Warning
If you choose to install modpack overrides, your existing configs may be overwritten
You can see all the mods in your current profile by running ferium list
. If you want to see more information about them, you can run ferium list -v
or ferium list --verbose
.
You can remove any of your mods by running ferium remove
, selecting the ones you would like to remove by using the space key, and pressing enter once you're done.
You can also provide the names of the mods to remove as arguments. Mod names with spaces have to be given in quotes (ferium remove "ok zoomer"
) or the spaces should be escaped (ferium remove ok\ zoomer
).
If some mod is compatible with your profile but ferium does not download it, create an issue if you think it's a bug. You can disable the game version or mod loader checks by using the --dont-check-game-version
and/or --dont-check-mod-loader
flags when adding the mod, or manually setting check_game_version
or check_mod_loader
to false for the specific mod in the config.
For example, Just Enough Items does not specify the mod loader for older minecraft versions such as 1.12.2
. In this case, you would add JEI by running ferium add 238222 --dont-check-mod-loader
so that the mod loader check is disabled.
You can also manually disable the mod loader (and/or game version) check(s) in the config like so
{
"name": "Just Enough Items (JEI)",
"identifier": {
"CurseForgeProject": 238222
},
"check_mod_loader": false
}
When adding a modpack, you will configure the following:
- Output directory
- This defaults to
.minecraft
, which is the default Minecraft resources directory. You don't need to worry about this if you play with Mojang's launcher (unless you changed the resources directory)
- This defaults to
- Whether to install modpack overrides
You can also provide these settings as flags. Ferium will automatically switch to the newly added modpack.
You can configure these same settings afterwards by running ferium modpack configure
.
Again, you can provide these settings as flags.
You can see all the modpack you have configured by running ferium modpack list
.
Switch between your modpacks using ferium modpack switch
.
Delete a profile by running ferium modpack delete
and selecting the modpack you want to delete.
You can create a profile by running ferium profile create
and configuring the following:
- Output directory
- This defaults to
.minecraft/mods
where.minecraft
is the default Minecraft resources directory. You don't need to worry about this if you play with Mojang's launcher (unless you changed the resources directory)
- This defaults to
- Name of the profile
- Minecraft version
- Mod loader
You can also provide these settings as flags.
If you want to copy the mods from another profile, provide the --import
flag. You can also directly provide a profile name to the flag if you don't want a profile picker to be shown.
Ferium will automatically switch to the newly created profile.
You can configure those same settings afterwards by running ferium profile configure
.
Again, you can provide these settings as flags.
You can see all the profiles you have by running ferium profile list
.
Switch between your profiles using ferium profile switch
.
Delete a profile by running ferium profile delete
and selecting the profile you want to delete.
If you would like to make a feature request, check the issues to see if the feature has already been added or is planned. If not, create a new issue.
Firstly, you need the Rust toolchain which includes cargo
, rustup
, etc. You can install these from the Rust website.
You can manually run cargo commands, but I recommend just
, a command runner that's basically a much better version of make
.
To build the project and install it to your Cargo binary directory, clone the project and run just install
. If you want to install it for testing purposes run just
(alias to just install-dev
), which builds in debug mode.
You can run clippy lints using just lint
, integration tests using cargo test
, and delete all build and test artefacts using just clean
.
If you would like to see instructions for building for specific targets (e.g. Linux ARM), head over to the workflow file.