Installing Moccasin

Note

Beginner Developers:

Are you a new or beginner python developer? Then follow these steps:

1. Install uv

2. Install moccasin in an isolated environment

3. Check to see if it worked

4. Go to the quickstart!

There are a few things you’ll need on your machine before you can install Moccasin. Please install the appropriate tools from the Prerequisites section. Once you have those, the recommended way to install Moccasin is via uv.

Prerequisites

1. Python 3.11 or later (">= 3.11, <= 3.13")

Installation with uv

For those unfamiliar, uv is a fast python package manager that helps us install moccasin into it’s own isolated virtual environment, so we don’t get any weird dependency conflicts with other python packages. It’s similar to pip and pipx if you’ve used them before. It even comes with some pip compatibility, will tools like uv pip install.

It’s highly recommended you understand how virtual environments work as well.

The easiest way to install uv is:

linux / MacOSWindows

curl -LsSf https://astral.sh/uv/install.sh | sh

But you can head over to the uv installation instructions for more options. If you don’t have at least Python 3.11 installed, you’ll need to install that first.

uv python install 3.11

Hint

You can do the same with Python 3.12 or 3.13. Moccasin is currently only compatible with Python 3.11, 3.12, and 3.13.

Isolated Environment

To install moccasin into an isolated environment with uv, run:

uv tool install moccasin

If you wish to install moccasin and use other python packages in your scripts, you’ll use the with flag:

uv tool install moccasin --with pandas

Note

Installing moccasin into a virtual environment (via uv tools install or pipx install) will require a different setup for injecting python packages. See Python packages in your scripts for more information.

Then, go to after installation.

Virtual Environment

If instead, you’d prefer to have different mox executeables Or, if you want to have moccasin installed with a traditional virtual environment set, you can run:

uv init
uv venv
source .venv/bin/activate

Then, you can install it as a uv installation:

uv add moccasin

Where you’ll be able to run the executeable with uv run mox instead of mox (see after installation).

Or a pip installation:

uv pip install moccasin

Where you’ll be able to run the executeable with mox (see after installation).

Installation with pipx

Pipx is a tool to help you install and run end-user applications written in Python. It’s roughly similar to macOS’s brew, JavaScript’s npx, and Linux’s apt.

pipx installs Moccasin into a virtual environment and makes it available directly from the commandline. Once installed, you will never have to activate a virtual environment prior to using Moccasin.

pipx does not ship with Python. If you have not used it before you will probably need to install it.

You can either head over to the pipx installation instructions or follow along below.

To install pipx:

python -m pip install --user pipx
python -m pipx ensurepath

Note

You may need to restart your terminal after installing pipx.

To install moccasin then with pipx:

pipx install moccasin

Note

Installing moccasin into a virtual environment (via uv tools install or pipx install) will require a different setup for injecting python packages. See Python packages in your scripts for more information.

Then, go to after installation.

Installation with poetry

Poetry is depedency management tool in Python. It allows to install/update libraries from your project, and also handle Python packaging.

poetry installs dependencies into its default virtual environment {cache-dir}/virtualenvs related to the intialized project. See how poetry virtual environment works.

You can install Moccasin with poetry, and if you do so, it’s highly recommended you understand how virtual environments work.

You can either head over to the poetry installation instructions or follow along below.

To install poetry, you’ll need pipx:

pipx install poetry

Note

You may need to restart your terminal after installing poetry.

Ensure poetry is available:

poetry --version
# Poetry (version 2.0.1)

We’ll need to initialize a poetry project to use its dedicated virtual enviroment to add Moccasin:

poetry new mox-project
cd mox-project

This will create the following directory structure for the mox-project dir:

.
├── mox-project
│   ├── mox_project
│   │   └── __init__.py
│   ├── poetry.lock
│   ├── pyproject.toml
│   ├── README.md
│   └── tests
│       └── __init__.py

You can now navigate to the mox-project folder and install Moccasin:

cd mox-project
poetry add moccasin

Caution

You may run into an issue where the default Python version registered in the pyproject.toml is not compatible with moccasin.

The current project's supported Python range (>=3.12) is not compatible with some of the required packages Python requirement:
- moccasin requires Python <=3.13,>=3.11, so it will not be satisfied for Python >3.13

Because no versions of moccasin match >0.3.6,<0.4.2
and moccasin (0.3.6) requires Python <=3.13,>=3.11, moccasin is forbidden.
So, because mox-project depends on moccasin (^0.3.6), version solving failed.

To fix this you’ll have to change manually the param requires-python. For example:

[project]
requires-python = ">=3.12,<=3.13"

Adapt the python version at your convinience. You might need to redo poetry add moccasin until the error message from poetry is gone

You can then activate your poetry env:

eval $(poetry env activate)

Then, go to after installation.

Installation with pip

You can install with pip, and if you do so, it’s highly recommended you understand how virtual environments work.

To install with pip:

pip install moccasin

Then, go to after installation.

From source

To install from source, you’ll need the uv tool installed. Once installed, you can run:

git clone https://github.com/cyfrin/moccasin
cd moccasin
uv sync
source .venv/bin/activate
uv pip install -e .

And you will have mox in your virtual environment created from the uv tool. It’s highly recommended you understand how virtual environments work.

Then, go to after installation.

After installation

Once installed, to verify that Moccasin is installed, you can run:

mox --version

And see an output like:

Moccasin CLI v0.1.0