Installation#

This page describes how to install RobotSwarmSimulator.

Setting up your environment#

Note

If you’re on Ubuntu or a Debian-based Linux distribution, you may need to use pyenv to install Python 3.11 or later. See the pyenv installation instructions. You need to do this before creating the virtual environment.

Important

Windows users: please DO NOT use Python from the Microsoft Store. Instead, download and install the latest version of Python from the Python website. Make sure to check the box to add Python to your PATH:

Add Python to PATH

If you didn’t do this when installing Python, you’ll need to add it manually. See Excursus: Setting environment variables or How to Add Python to PATH. Or, uninstall and reinstall Python (You may need to re-pip install system Python packages).

To install RobotSwarmSimulator, we recommend using uv.

Install UV for faster installs
Install uv <pyuv/uv> for faster installs#
pip install uv -U

The -U flag is shorthand for --upgrade.

You can preface most pip install commands with uv for much faster installation. uv pip install may not work for some packages. If you get an error, try using regular pip install first.

The recommended way to install RobotSwarmSimulator is with a virtual environment.

Virtual environments are isolated Python environments that allow you to install packages without affecting your system Python installation.

First, you need to choose a location to store your virtual environment.

mkdir swarm
cd swarm
Create a virtual environment#
uv venv
Create a virtual environment#
pip install virtualenv
virtualenv .venv --prompt .

This will create a virtual environment .venv folder in your current directory.

Now, we need to activate the virtual environment.

Activating the virtual environment#

Once you have created your virtual environment, you need to activate it.

Make sure you’re in the directory where you created the virtual environment. In this example we’re in the swarms/ folder.

Make sure you’re in the directory where you created the virtual environment, which should contain Scripts\\ and Lib\\ and pyvenv.cfg among other things. You can see what’s in your current folder by typing dir in the command prompt.

.venv\Scripts\activate

Make sure you’re in the directory where you created the virtual environment, which should have a bin/ and lib/ and pyvenv.cfg among other things. You can see what’s in your current folder by typing ls in the command prompt.

source .venv/bin/activate

Activating fish, Nushell, or PowerShell

The above activation command is for the default shell environments, such as bash, zsh, or sh on Unix, or cmd and powershell on Windows. If you’re using a different shell, such as fish or Nushell, or if you’re using PowerShell and have activation issues, you may need to use a different activation file.

source .venv/bin/activate.fish

.venv\Scripts\activate.ps1

Note: Windows users may need to change their PowerShell script execution policy. See the dropdown below:

Script Execution Policy

If you see an error like this:

PS > .\.venv\Scripts\activate.ps1
.\.venv\Scripts\activate.ps1 : File .venv\Scripts\activate.ps1 cannot be loaded because running
scripts is disabled on this system. For more information, see about_Execution_Policies at
https:/go.microsoft.com/fwlink/?LinkID=135170 .
At line:1 char:1
+ .\.venv\Scripts\activate.ps1
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

Your script execution policy may be set to Restricted (check with Get-ExecutionPolicy).

To fix this, first open an administrator terminal. You can do this by right-clicking on the Start button or pressing ⊞Win+x and selecting Terminal (Admin) (or similar). Then, run the following command:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

You will need to close and re-open your terminal windows for this to take effect.

overlay use .venv\Scripts\activate.nu

overlay use .venv/bin/activate.nu

You should see the name of your virtual environment in parentheses at the beginning of your terminal prompt:

(swarms) C:\swarms>

(swarms) user@host:~/swarms$

To deactivate the virtual environment, use the deactivate command:

deactivate

Installing RobotSwarmSimulator#

To install RobotSwarmSimulator, we recommend using uv. You can preface most pip install commands with uv for much faster installation.

Don’t forget to activate the virtual environment!

Activating the virtual environment

pip install uv
uv pip install swarmsim

Note

It’s possible to install RobotSwarmSimulator to the global system Python installation with the --system flag. However, this is not recommended, as it may cause conflicts with other packages.

pip install swarmsim

While you’re here, let’s also install pyreadline3 which makes the python shell much more user-friendly.

uv pip install pyreadline3

pip install pyreadline3

If the installation was successful, you should be able to open a python shell and import the package:

python#
Python 3.11.0 (or newer)
Type "help", "copyright", "credits" or "license" for more information.
>>> import swarmsim
>>>

If you installed pyreadline3, you can exit the python shell with Ctrl+C to stop currently running commands and then Ctrl+D or quit() to quit the python REPL.

Development Installations#

If you intend to contribute to or modify RobotSwarmSimulator, you should follow the installation guide for development instead.

Installing for Development

WSL Installation#

Although RobotSwarmSimulator works natively on Windows, you can also install RobotSwarmSimulator in a Windows Subsystem for Linux (WSL) environment.

First, you need to install WSL.

Then, follow the Installing RobotSwarmSimulator or Installing for Development instructions as if you were on Linux.

Finished installing? Check out the Basic Usage tutorial.

First Run Tutorial