Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 36 ยท Getting Started

Installing Nim and Nimble

Install the Nim compiler and the Nimble package manager on Windows, macOS or Linux, check your setup, pick an editor and understand version requirements.

To write Nim on your own machine you need two things: the compiler (nim) and a C compiler it can call. Nim ships with its package manager, Nimble, so you get both tools from one download. This lesson shows the common installation routes, how to check that everything works, and how Nimble describes version requirements.

Nim cannot be run on this site, so the commands below are read-only. Commands and options are from Nim 2.2; if you use another release, nim --help and the official documentation are the final word.

What you need

Piece Purpose
nim The compiler. Translates .nim files to C and drives the build.
nimble Package manager and project tool (dependencies, tests, tasks).
C compiler GCC or Clang on Linux and macOS; on Windows the official download bundles MinGW-w64.
Editor Any text editor. VS Code with the Nim extension, Vim, Emacs and JetBrains tools work well.

Installation routes

Official download

The simplest route on Windows is the zip or installer from the Nim website. Unzip it, then add the bin folder to your PATH. The Windows archive already contains a C compiler, so you can compile immediately.

Version managers

The community provides small tools that install and switch between Nim versions, for example choosenim and grabnim. They download a release, set up PATH, and let you keep a stable and a newer version side by side. Check the Nim website for the currently recommended one before you install.

Package managers

Most Linux distributions and Homebrew on macOS ship a nim package. These can lag behind the newest release, which is fine for learning:

Terminal
# macOS with Homebrew
brew install nim

# Debian / Ubuntu (version may be older)
sudo apt install nim

Building from source

The Nim repository includes a bootstrap script. Download the source archive, run sh build.sh (or build_all.sh), and then build the full toolchain with koch. This takes a few minutes and is mostly useful for developers who need the very latest compiler.

Check the installation

Open a new terminal (so PATH updates apply) and run:

Terminal
nim --version
nimble --version
gcc --version      # or: clang --version

nim --version prints the compiler version and the default backend information. If gcc is not found on Linux, install build-essential (Debian/Ubuntu) or your distribution's equivalent. On macOS install the command line tools with xcode-select --install.

Common problems

  • "nim is not recognized" / "command not found". The bin folder is not on PATH, or the terminal was opened before you changed it.
  • "gcc not found". Install a C compiler; Nim needs one on the default backend.
  • Old version from a package manager. Use a version manager or the official archive if a tutorial needs a newer feature.
  • Antivirus warnings on Windows. Freshly built executables sometimes trigger scanners. Add your project folder to the exceptions if it keeps happening.

Editors

Nim has a language server, nimlangserver, which provides completion, go-to-definition and diagnostics in editors that support the Language Server Protocol. In VS Code, install the Nim extension and let it install the server. A basic setup also needs only syntax highlighting; you can always compile from a terminal.

Meet Nimble

Nimble reads a .nimble file at the root of a project. A small one looks like this:

NIM
# mytool.nimble
version       = "0.1.0"
author        = "You"
description   = "A small tool"
license       = "MIT"
srcDir        = "src"
bin           = @["mytool"]

requires "nim >= 2.0.0"
requires "regex >= 0.20.0"

The requires lines are the interesting part. Each one names a package and a version constraint such as >= 2.0.0, ~= 1.2 (compatible with 1.2.x) or == 1.4.0. nimble install downloads dependencies and nimble build builds your program. You will build a complete project in the tooling chapter.

Terminal
nimble init mytool     # create a project skeleton
nimble build           # compile the binary
nimble run             # build and run
nimble test            # run tests in the tests folder

A stand-in: checking a version requirement

Nimble compares versions as dotted numbers. This C stand-in (not Nimble's real code) shows the idea: split the version into numbers and compare them from left to right.

C Stand-in: compare versions like a requires line

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Notice that 2.0.0 passes >= 2.0.0 because the comparison allows equality. Comparing numbers, not strings, is important: as text, "2.10" sorts before "2.9", which is wrong for versions.

Keeping things tidy

Create one folder per project and keep the compiler's output out of version control. Nim writes temporary C files to a nimcache folder (inside your user cache directory by default). You can add the compiled binary name to .gitignore as well. Nimble stores downloaded packages under ~/.nimble (on Windows, in your user profile), shared by all projects.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the default Nim setup need a C compiler?

    The default backend generates C, then calls GCC or Clang.
  2. 2. What is Nimble?

    Nimble manages dependencies and builds, using a .nimble file.
  3. 3. You get 'command not found' after installing. What is the most likely cause?

    Add the folder containing nim and nimble to PATH and open a fresh terminal.
  4. 4. Why compare versions as numbers and not as text?

    Dotted version numbers compare part by part numerically.

Summary

  • You need the Nim compiler, Nimble (bundled) and a C compiler.
  • Install from the official archive, a version manager or a system package manager; verify with nim --version.
  • nimble init, build, run and test manage a project, and requires lines declare dependencies with version constraints.
  • Editors work through the Nim language server.

Next: Hello, Nim: compile and run