The aim of this tutorial is to give you the basics of programming and the Nim syntax so you can have an easier time following other tutorials and/or explore further by yourself.

Instead of just reading what is written, it would be the best if you try the stuff by yourself, modify the examples, think of some examples of your own, and be curious in general. The exercises at the end of some chapters should be non-negotiable — don’t skip them.

If you need additional help understanding some parts of the tutorial or with the exercises, you can always ask for help on the Nim forum, the Nim Gitter channel, their Discord server, or Nim’s IRC channel on freenode, #nim.

Nim has ready made distributions for all three major operating systems and there are several options when it comes to installing Nim.

You can follow the official installation procedure to install the latest stable version, or you can use a tool called choosenim which enables you to easily switch between the stable and the latest development version if you’re interested in the latest features and bugfixes.

Whichever way you choose, just follow the installation procedure explained at each link and Nim should be installed. We will check that the installation went well in a coming chapter.

If you’re using Linux, there is a high probability that your distribution has Nim in the package manager. If you are installing it that way, make sure it’s the most recent version (see the website for what is the latest version), otherwise install via one of two methods mentioned above.

In this tutorial we will use the stable version. Originally, this tutorial was written for Nim 0.19 (released in September 2018), and it should work for any newer version, including Nim 1.0.

You can write Nim code in any text editor, and then compile and run it from the terminal. If you want syntax highlighting and code completion there are plugins for popular code editors which provide these features.

Most of Nim users prefer the VS Code editor, with the Nim extension which provides syntax highlighting and code completion, and the Code Runner extension for quick compiling and running.

The author personally uses NeoVim editor, with this plugin which provides additional features like syntax highlighting and code completion.

If you’re using other code editors, see the wiki for available editor support.

To check if the installation was successful, we will write a program which is traditionally used as an introductory example: Hello World.

Printing (as in: displaying on the screen; not on a paper with a printer) the phrase Hello World! in Nim is straightforward and it doesn’t require any boilerplate code.

In a new text file called e.g. helloworld.nim we need to write just one line of code:

First we need to compile our program, and then run it to see if it works as expected.

Open your terminal in the same directory where your file is (on Linux you can get "Open Terminal here" if you right-click the directory in your file manager, on Windows you should use Shift + right-click to get the menu option for opening the command line).

We compile our program by typing in the terminal:

After a successful compilation, we can run our program. On Linux we can run our program by typing ./helloworld in the terminal, and on Windows we do it by typing helloworld.exe.

There is also a possibility to both compile and run the program with just one command. We need to type:

If you’re using VSCode with the Code Runner extension mentioned before, you’ll just have to press Ctrl+Alt+N and your file will be compiled and run.

Whichever way you chose to run your program, after a brief moment in the output window (or in your terminal) you should see:

Congratulations, you have successfully run your first Nim program!

Now you know how to print some stuff on the screen (using the echo command), compile your program (typing nim c programName.nim in your terminal), and run it (various possibilities).

We can now start to explore the basic elements which will help us to write simple Nim programs.

Nim is a statically typed programming language, meaning that the type of an assignment needs to be declared before using the value.

In Nim we also distinguish values that can change, or mutate, from those that can’t, but more on this later. We can declare a variable (a mutable assignment) using the var keyword, just by stating its name and type (the value can be added later) by using this syntax:

If we already know its value, we can declare a variable and give it a value immediately:

Nim also has type inference ability: the compiler can automatically detect the type of a name assignment from its value, without explicitly stating the type. We’ll look more into the various types in the next chapter.

So we can assign a variable without an explicit type like this:

An example of this in Nim looks like this:

When assigning names it is important to choose names that mean something for your program. Simply naming them a, b, c, and so forth will quickly become confusing. It is not possible to use spaces in a name, as that would split it into two. So if the name you choose consists of more than one word the usual way is to write it in camelCase style (notice that the first letter in a name should be lowercase).

Note however that Nim is both case- and underscore-insensitive meaning that helloWorld and hello_world would be the same name. The exception to this is the first character, which is case-sensitive. Names can also include both numbers and other UTF-8 characters, even emojis should you wish that, but keep in mind you and possibly others will have to type them.

Instead of typing var for each variable, multiple variables (not necessarily of the same type) can be declared in the same var block. In Nim, blocks are parts of code with the same indentation (same number of spaces before the first character), and the default indentation level is two spaces. You will see such blocks everywhere in a Nim program, not only for assigning names.

As previously mentioned variables are mutable, i.e. their value can change (multiple times), but their type must stay the same as declared.

Unlike variables declared with var keyword, two more types of assignment exist in Nim, whose value cannot change, one declared with the const keyword, and the other declared with the let keyword.

As seen in the previous chapter, integers are numbers which are written without a fractional component and without a decimal point.

For example: 32, -174, 0, 10_000_000 are all integers. Notice that we can use _ as a thousands separator, to make larger numbers more readable (it is easier to see that we’re talking about 10 million when it’s written as 10_000_000 rather than as 10000000).

The usual mathematical operators — addition (+), subtraction (-), multiplication (*), and division (/) — work as one would expect. The first three operations always produce integers, while dividing two integers always gives a floating point number (a number with a decimal point) as a result, even if two numbers can be divided without a remainder.

Integer division (division where the fractional part is discarded) can be achieved with the div operator. An operator mod is used if one is interested in the remainder (modulus) of an integer division. The result of these two operations is always an integer.

We can compile and run the above code, and the output should be:

Floating-point numbers, or floats for short, are an approximate representation of real numbers.

For example: 2.73, -3.14, 5.0, 4e7 are floats. Notice that we can use scientific notation for large floats, where the number after the e is the exponent. In this example, 4e7 is a notation representing 4 * 10^7.

We can also use the four basic mathematical operations between two floats. Operators div and mod are not defined for floats.

The precedence of mathematical operations is as one would expect: multiplication and division have higher priority than addition and subtraction.

The char type is used for representing a single ASCII character.

Chars are written between two single ticks ('). Chars can be letters, symbols, or single digits. Multiple digits or multiple letters produce an error.

Strings can be described as a series of characters. Their content is written between two double quotes (").

We might think of strings as words, but they can contain more than one word, some symbols, or digits.

A boolean (or just bool) data type can only have two values: true or false. Booleans are usually used for control flow (see next chapter), and they are often a result of relational operators.

The usual naming convention for boolean variables is to write them as a simple yes/no (true/false) questions, e.g. isEmpty, isFinished, isMoving, etc.

This was the longest chapter in this tutorial and we covered a lot of ground. Take your time to go trough each data type and experiment with what you can do with each of them.

Types might seem like a restriction at first, but they allow the Nim compiler to both make your code faster, and make sure you’re not doing something wrong by accident — this is especially beneficial in large code bases.

Now you know the basic data types and several operations on them, which should be enough to do some simple calculations in Nim. Test your knowledge by doing the following exercises.

An if statement as shown above is the simplest way to branch our program.

The Nim syntax for writing if statement is:

If statements can be nested, i.e. inside one if-block there can be another if statement.

A case statement is another way to only choose one of multiple possible paths, similar to the if statement with multiple elifs. A case statement, however, doesn’t take multiple boolean conditions, but rather any value with distinct states and a path for each possible value.

Code written with in if-elif block looking like this:

can be written with case statement like this:

Unlike the if statement, case statement must cover all possible cases. If one is not interested in some of those cases, else: discard can be used.

We can also use multiple values for each branch if the same action should happen for more than one value.

Syntax of a for-loop is:

Traditionally, i is often used as a loopVariable name, but any other name can be used. That variable will be available only inside the loop. Once the loop has finished, the value of the variable is discarded.

The iterable is any object we can iterate through. Of the types already mentioned, strings are iterable objects. (More iterable types will be introduced in the next chapter.)

All lines in the loop body are executed at every loop, which allows us to efficiently write repeating parts of code.

If we want to iterate through a range of (integer) numbers in Nim, the syntax for the iterable is start .. finish where start and finish are numbers. This will iterate through all the numbers between start and finish, including both start and finish. For the default range iterable, start needs to be smaller than finish.

If we want to iterate until a number (not including it), we can use ..<:

If we want to iterate through a range of numbers with a step size different than one, countup is used. With countup we define the starting value, the stopping value (included in the range), and the step size.

To iterate through a range of numbers where the start is larger than finish, a similar function called countdown is used. Even if we’re counting down, the step size must be positive.

Since string is an iterable, we can use a for-loop to iterate through each character of the string (this kind of iteration is sometimes called a for-each loop).

If we also need to have an iteration counter (starting from zero), we can achieve that by using for <counterVariable>, <loopVariable> in <iterator>: syntax. This is very practical if you want to iterate through one iterable, and simultaneously access another iterable at the same offset.

While loops are similar to if statements, but they keep executing their block of code as long as the condition remains true. They are used when we don’t know in advance how many times the loop will run.

We must make sure the loop will terminate at some point and not become an infinite loop.

The break statement is used to prematurely exit from a loop, usually if some condition is met.

In the next example, if there were no if statement with break in it, the loop would continue to run and print until i becomes 1000. With the break statement, when i becomes 3, we immediately exit the loop (before printing the value of i).

The continue statement starts the next iteration of a loop immediately, without executing the remaining lines of the current iteration. Notice how 3 and 6 are missing from the output of the following code:

An array is the simplest container type. Arrays are homogeneous, i.e. all elements in an array must have the same type. Arrays are also of a constant size, meaning that the amount of elements (or rather: the amount of possible elements), must be known at compile-time. This means that we call arrays a "homogeneous container of a constant length".

The array type is declared using array[<length>, <type>], where length is the total capacity of the array (number of elements it can fit), and type is a type of all its elements. The declaration can be omitted if both length and type can be inferred from the passed elements.

The elements of an array are enclosed inside of square brackets.

Since the length of an array has to be known at compile-time, this will not work:

Sequences are containers similar to arrays, but their length doesn’t have to be known at compile time, and it can change during runtime: we declare only the type of the contained elements with seq[<type>]. Sequences are also homogeneous, i.e. every element in a sequence has to be the same type.

The elements of a sequence are enclosed between @[ and ].

Another way to initialize an empty sequence is to call the newSeq procedure. We’ll look more at procedure calls in the next chapter but for now just know that this is also a possibility:

We can add new elements to a sequence with the add function, similar to how we did with strings. For this to work the sequence must be mutable (defined with var), and the element we’re adding must be of the same type as the elements in the sequence.

Trying to pass different types to the existing sequences will produce an error:

Since sequences can vary in length we need a way to get their length, for this we can use the len function.

Indexing allows us to get a specific element from a container by its index. Think of the index as a position inside of the container.

Nim, like many other programming languages, has zero-based indexing, meaning that the first element in a container has the index zero, the second element has the index one, etc.

If we want to index "from the back", it is done by using the ^ prefix. The last element (first from the back) has index ^1.

The syntax for indexing is <container>[<index>].

Slicing allows us to get a series of elements with one call. It uses the same syntax as ranges (introduced in the for loop section).

If we use start .. stop syntax, both ends are included in the slice. Using start ..< stop syntax, the stop index is not included in the slice.

The syntax for slicing is <container>[<start> .. <stop>].

Both indexing and slicing can be used to assign new values to the existing mutable containers and strings.

Both of the containers we’ve seen so far have been homogeneous. Tuples, on the other hand, contain heterogeneous data, i.e. elements of a tuple can be of different types. Similarly to arrays, tuples have fixed-size.

The elements of a tuple are enclosed inside of parentheses.

We can also name each field in a tuple to distinguish them. This can be used for accessing the elements of the tuple, instead of indexing.

Before we can use (call) our procedure, we need to create it and define what it does.

A procedure is declared by using the proc keyword and the procedure name, followed by the input parameters and their type inside of parentheses, and the last part is a colon and the type of the value returned from a procedure, like this:

The body of a procedure is written in the indented block following the declaration appended with a = sign.

Normally we’re not allowed to change any of the parameters we are given. Doing something like this will throw an error:

In order for this to work we need to allow Nim, and the programmer using our procedure, to change the argument by declaring it as a variable:

This of course means that the name we pass it must be declared as a variable as well, passing in something assigned with const or let will throw an error.

While it is good practice to pass things as arguments it is also possible to use names declared outside the procedure, both variables and constants:

After we have declared a procedure, we can call it. The usual way of calling procedures/functions in many programming languages is to state its name and provide the arguments in the parentheses, like this:

The result from calling a procedure can be stored in a variable.

If we want to call our findMax procedure from the above example, and save the return value in a variable we can do that with:

Nim, unlike many other languages, also supports Uniform Function Call Syntax, which allows many different ways of calling procedures.

This one is a call where the first argument is written before the function name, and the rest of the parameters are stated in parentheses:

We have used this syntax when we were adding elements to an existing sequence (<seq>.add(<element>)), as this makes it more readable and expresses our intent more clearly than writing add(<seq>, <element>). We can also omit the parentheses around the arguments:

We’ve seen this style being used when we call the echo procedure, and when calling the len procedure without any arguments. These two can also be combined like this, but this syntax however is not seen very often:

The uniform call syntax allows for more readable chaining of multiple procedures:

In Nim, every procedure that returns a value has an implicitly declared and initialized (with a default value) result variable. The procedure will return the value of this result variable when it reaches the end of its indented block, even with no return statement.

Note that this procedure is here to demonstrate the result variable, and it is not 100% correct: if you would pass a sequence containing only negative numbers, this procedure would return 0 (which is not contained in the sequence).

Inside of a procedure we can also call other procedures.

As mentioned in the very beginning of this section we can declare a procedure without a code block. The reason for this is that we have to declare procedures before we can call them, doing this will not work:

The way to get around this is what’s called a forward declaration:

Test all procedures by calling them with different parameters.

If we want to import a module and all of its functionality, all we have to do is put import <moduleName> in our file. This is commonly done on the top of the file so we can easily see what our code uses.

Often times we have so much code in a project that it makes sense to split it into pieces that each does a certain thing. If you create two files side by side in a folder, let’s call them firstFile.nim and secondFile.nim, you can import one from the other as a module:

In case you have more than these two files, you might want to organize them in a subdirectory (or more than one subdirectory). With the following directory structure:

if you wanted to import all other files in your secondFile.nim this is how you would do it:

Let’s say we have a text file called people.txt in the same directory as our Nim code. The contents of that file looks like this:

We want to use the contents of that file in our program, as a list (sequence) of names.

To solve the problem of a final new line, we can use the strip procedure from strutils after we have read from a file. All this does is remove any so-called whitespace from the start and end of our string. Whitespace is simply any character that makes some space, new-lines, spaces, tabs, etc.

If we want to interact with a user, we must be able to ask them for an input, and then process it and use it. We need to read from standard input (stdin) by passing stdin to the readLine procedure.

Reading from a file or from a user input always gives a string as a result. If we would like to use numbers, we need to convert strings to numbers: we again use the strutils module and use parseInt to convert to integers or parseFloat to convert into a float.

If we have file numbers.txt in the same directory as our Nim code, with the following content:

and we want to read that file and find the sum and average of the numbers provided, we can do something like this:

If you want to continue learning from Nim tutorials:

If you want to solve some programming puzzles:

Happy coding!

The source files are available on Github.