Toolchain & Environment

Installing Nim takes minutes because the distribution is one compiler that delegates code generation to a C compiler you already have. This lesson installs the toolchain, runs a first program, and maps the commands and project layout you will use every day.

Install the Toolchain

Nim ships as a single nim executable plus the standard library. There is no runtime to install and no virtual environment to activate: the compiler reads your source, emits C, and calls the system C compiler.

Install and Manage Versions with choosenim

choosenim is the official version manager for Linux, macOS and WSL. It installs the compiler and the Nimble package manager, and lets you switch versions per project.

# Linux/macOS/WSL — official installer script
curl https://nim-lang.org/choosenim/init.sh -sSf | sh

# Then manage versions with choosenim itself
choosenim stable          # install and select the current stable release
choosenim 2.2.0           # pin an exact version for a legacy project
choosenim update stable   # upgrade within the stable channel

Windows and Package Managers

On Windows the download page provides a self-contained installer (nim-2.x.x_x64.exe), which needs no separate C compiler because the official build bundles one (mingw-w64). Package managers work too if you already maintain a toolchain that way.

Platform	Recommended route	Note
Windows	Installer from nim-lang.org/install_windows	Bundled MinGW compiler: nothing else to install.
macOS	`choosenim` or `brew install nim`	`choosenim` gives you version switching.
Linux / WSL	`choosenim` (preferred) or your distro package	Distro packages often lag behind the current release.

Verify the Installation

Two commands prove the toolchain is complete. If nimble is missing, the package manager was not installed — reinstall with choosenim, which always installs both.

nim --version      # Nim Compiler Version 2.x.x [Windows: amd64]
nimble --version   # Nimble Package Manager — needed for project dependencies near the end of this track

# The system C compiler produces the final machine code; Nim selects one for you.
nim c --listCmd hello.nim   # prints the C invocation Nim would run, without compiling

Your First Program

Create one file and compile it. Everything you write in this track follows the same rhythm: compile, then run — or let the compiler do both with a single command.

Compile and Run

# hello.nim — the smallest complete Nim program
echo "Hello from Nim"   # echo writes one line to stdout; no import required

for i in 1 .. 3:        # '1 .. 3' is an inclusive range, so the loop runs 1, 2, 3
  echo "line ", i       # echo accepts several arguments and prints them in order

nim c hello.nim       # compile to a native binary (hello.exe on Windows)
nim r hello.nim       # compile AND run — the command you will use most while learning
./hello               # run the produced binary directly

The Command Set Worth Memorizing

The compiler's first argument selects what to produce. These six cover almost all day-to-day work.

Command	What it does	When to use it
`nim r file.nim`	Compile and immediately run	Learning, scripting, quick experiments
`nim c file.nim`	Compile with the C backend	Normal debug builds
`nim c -d:release file.nim`	Compile optimized, runtime checks still on	Benchmarks and shipped binaries
`nim cpp file.nim`	Compile through a C++ backend	Libraries that need C++ interop
`nim js file.nim`	Emit JavaScript instead of native code	Browser and Node targets
`nim check file.nim`	Type-check only, no code generation	Fast feedback in a tight edit loop

Where the Artifacts Go

Compilation leaves two kinds of output: the finished binary next to your source (rename it with -o:name, relocate it with --outdir:path) and a cache of generated C. The cache makes rebuilds fast; deleting it forces a clean rebuild when you suspect stale output.

nim c --outdir:build -o:hello_nim hello.nim   # produces build/hello_nim[.exe]
rm -rf nimcache                               # force a fresh C generation
nim c --nimcache:/tmp/nimcache hello.nim      # keep generated C outside the project

Project Layout and Nimble

A single file is fine until you need dependencies and tests. At that point Nimble — the package manager bundled with Nim — gives every project the same shape.

Scaffold with nimble init

nimble init calculator      # answer a few questions, get a working skeleton
cd calculator && ls
# calculator.nimble    package manifest (metadata, dependencies, tasks)
# src/calculator.nim   module source
# tests/test1.nim      test entry point wired to 'nimble test'

The .nimble Manifest

The manifest is NimScript — Nim code executed by Nimble — so tasks can contain real logic, not just command strings.

# calculator.nimble — metadata read by nimble build / install / test
version     = "0.1.0"
author      = "Your Name"
description = "A small CLI calculator used to learn Nim"
license     = "MIT"
srcDir      = "src"            # where nimble looks for sources to compile

requires "nim >= 2.0.0"        # compiler baseline for this package
# requires "cligen >= 1.7"     # any nimble package is declared the same way

task test, "Run the unit tests":   # 'nimble test' executes this task body
  exec "nim c -r tests/test1.nim"  # NimScript: strings are commands, code is Nim

The Nimble Commands You Will Use

nimble install      # install a dependency into your user-wide package store
nimble build             # compile the package declared in the manifest
nimble test              # run the 'test' task
nimble develop           # link the current folder as an editable local package

Editor Support and Utilities

The distribution ships tooling that turns a plain editor into a Nim IDE. Install the extension for your editor and point it at the compiler; the language server supplies completion, hover documentation and inline errors.

Language Server, Formatter, Search

nimsuggest ships with the compiler, while nimlangserver is the current official Language Server Protocol implementation and is installed with Nimble. Formatting, documentation and code search are separate small tools that all come from the same ecosystem.

nimble install nimlangserver    # official LSP server used by editor extensions
nimpretty src/calculator.nim    # canonical formatter: normalizes names and whitespace
nimgrep --filenames 'proc .*calc' src   # fast regex search across a Nim tree
nim doc src/calculator.nim      # generate HTML API documentation from doc comments

First Practice

Recreate the hello program from memory, then change it so it prints the numbers 1 to 10. When that compiles and runs, continue with Syntax, Statements & Expressions. Every lesson from here on has at least one runnable file on the Lab Examples page.