Installing Moccasin¶
Note
Beginner Developers:
Are you a new or beginner python developer? Then follow these steps:
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¶
Python 3.11 or later
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:
curl -LsSf https://astral.sh/uv/install.sh | sh
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Note
⚠️ Windows users: We recommend you watch the first 10 minutes of this WSL tutorial and install and work with WSL. WSL stands for “Windows Subsystem for Linux” and it allows you to run a Linux commands on Windows machine. If you’re working on WSL, you can just use the linux / MacOS
command from the other tab.
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
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.0
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