GrabNim

A simple tool to install and switch between different versions of the Nim compiler.

Features

• Install pre-built Nim releases (stable builds from nim-lang.org and nightly builds from github)
• Install Nim from source (supports tagged versions and devel for master branch)
• Switch between installed versions
• Uses symlinks on Unix-like OSes and junctions on Windows
• Doesn't litter in Home directory, respects XDG spec

Table of Contents

• Features
• Quick Start
• Usage
• Migration from Choosenim
• Installation
• How GrabNim Works
• Advanced Usage
• Troubleshooting
• Building from Source
• License

Quick Start

# Install latest stable Nim
grabnim

# Install specific version
grabnim fetch
grabnim 2.2.4

# Switch between installed versions
grabnim list
grabnim 2.0.0

# Compile any version from source
grabnim compile 2.2.4
grabnim compile devel

Usage

Usage:
  grabnim                     Install and switch to latest stable version
  grabnim <version>           Install and switch to specific version
  grabnim compile <ver>       Clone Nim repo, compile and switch version
  grabnim upd|update <ver>    Update installed compiler (Devel or Nightly)
  grabnim del|delete <ver>    Delete local version of compiler
  grabnim path <ver>          Print path to specific installed compiler version

  grabnim fetch               List remote available versions
  grabnim list                List local installed versions

  grabnim off|disable         Disable grabnim link ('grabnim <ver>' to re-enable)
  grabnim ver|version         Print grabnim version
  grabnim info                Print detected platform and directories
  grabnim help                Display this help message

Windows only:
  grabnim setup               Download extra DLLs, install MinGW, and setup PATH

POSIX shells:
  grabnim use <ver>           Output shell command to set Nim compiler for
                              for current shell; overrides grabnim link

Examples:
  grabnim 2.2.4                 Install Nim v2.2.4 from official website
  grabnim devel                 Install Nightly Nim devel from github
  grabnim 2.2.x                 Install Nightly Nim latest-2-2 from github
  grabnim compile devel         Clone Nim repo and build master branch
  grabnim compile 2.0.8         Clone repo, switch to 'v2.0.8' tag and build
  grabnim update devel          Reset installed repo, pull and build
  grabnim update 2.2.x          Delete and reinstall latest-2-2 from github

  source <(grabnim use 2.2.4)   Set Nim v2.2.4 compiler for this shell session

Migration from Choosenim

To migrate smoothly, first clean up your Choosenim installation:

Linux/macOS:

rm -rf ~/.choosenim ~/.nimble/bin/{choosenim,nim,nimble,nim-gdb,nimgrep,nimpretty,nimsuggest,testament}

Windows:

1. Delete %USERPROFILE%\.choosenim
2. Remove choosenim shims from %USERPROFILE%\.nimble\bin: choosenim.exe nim.exe nim-gdb.exe nimgrep.exe nimble.exe nimpretty.exe nimsuggest.exe testament.exe

Installation

Quick Install (Linux/macOS/WSL/Cygwin/MSYS2)

wget https://codeberg.org/janAkali/grabnim/raw/branch/master/misc/install.sh
sh install.sh

Manual Installation

1. Download a binary from releases
2. Configure your PATH environment variable (see below)
3. (Optional) Move binary to a directory in your PATH or create a symlink

PATH Configuration

Add the GrabNim directory to your PATH environment variable. If you don't know how, see this gist.
Ensure that GrabNim path is set after the Nimble path, so Nimble-installed packages take precedence over compiler-bundled versions.

Linux/macOS:

export PATH="$HOME/.nimble/bin:$HOME/.local/share/grabnim/current/bin:$PATH"

Windows:

%USERPROFILE%\.nimble\bin;%LOCALAPPDATA%\grabnim\current\bin;

How GrabNim Works

Paths Used by GrabNim

Cache Directory (cached nim-repo and csources):

• Windows: System %TEMP% (e.g. C:\Users\YourUser\AppData\Local\Temp)
• Linux/macOS: $XDG_CACHE_HOME/grabnim-cache or ~/.cache/grabnim-cache if XDG_CACHE_HOME is not set

GrabNim Directory (installed Nim compilers):

• Windows: %LOCALAPPDATA%\grabnim (e.g., C:\Users\YourUser\AppData\Local\grabnim)
• Linux/macOS: $XDG_DATA_HOME/grabnim or ~/.local/share/grabnim if XDG_DATA_HOME is not set

Each version lives in its own subfolder (e.g., nim-2.0.0, nim-devel)

Version Switching

GrabNim creates a current symlink (junction on Windows) in the GrabNim Directory that points to the selected version folder. When you add .../grabnim/current/bin to your PATH, it'll always point to currently active Nim version binaries.

Advanced Usage

Custom Local Compiler Versions

You can add your own Nim compiler builds by placing them in GrabNim Directory with local- prefix. Custom compilers appear in grabnim list and can be switched to like any other version.

Example:

# Copy your custom Nim build
cp -r /path/to/custom/nim ~/.local/share/grabnim/local-mybuild

# Verify it appears in the list
grabnim list

# Switch to your custom build
grabnim local-mybuild

Requirements for custom compilers:

• Directory name must start with local-
• Must contain nim executable in bin subdirectory

Troubleshooting

GitHub API 403 Errors (Rate Limits / Access Denied)

If you see an error like:

Failed to fetch from 'https://api.github.com/...'. Error: 403 (rate limit exceeded or access denied)

It's probably because GitHub API has strict rate limits for unauthenticated requests (60/hour). To fix this:

1. Create a GitHub Personal Access Token (PAT)

1. Go to GitHub → Settings → Developer Settings → Fine-grained tokens
2. Generate new token
3. Choose a name (e.g., grabnim-public-readonly)
4. Choose Expiration Date (90 days or No expiration)
5. Select Repository Access: Public repositories (read-only access to public repos)
6. Generate token
7. Copy token string (it is shown only once)

2. Use the PAT

Local Use:

• Linux (Bash):

  echo 'export GRABNIM_GITHUB_TOKEN="your_token_here"' >> ~/.bashrc
  source ~/.bashrc
  

• macOS (Zsh):

  echo 'export GRABNIM_GITHUB_TOKEN="your_token_here"' >> ~/.zshrc
  source ~/.zshrc
  

• Windows (CMD):

  setx GRABNIM_GITHUB_TOKEN "your_token_here" /m
  

GitHub Actions (CI/CD):

1. Add token to your repo secrets:

• Go to Settings → Secrets → Actions → New repository secret
• Name: GRABNIM_GITHUB_TOKEN
• Secret: Paste your PAT token

2. Use in workflow:

   - name: Install Nim
     env:
       GRABNIM_GITHUB_TOKEN: ${{ secrets.GRABNIM_GITHUB_TOKEN }}
     run: grabnim
   

Building from Source

Prerequisites

• Nim compiler v2.0.0 or later
• C compiler
• Git

Build Steps

1. Clone the repository:

   git clone https://codeberg.org/janakali/grabnim
   cd grabnim
   

2. Build with Nim:

   nim c -d:release grabnim
   

License

This project is licensed under the MIT License. See the LICENSE file for details.