Installation Guide
This guide will walk you through setting up a Python virtual environment for running the example apps which utilize Cobra plugins.
Environment Setup
Setting up your environment is done in three steps: installing native dependencies, cloning the pntOS-Python project, and setting up your Python environment.
Install Native Dependencies
Please ensure you have the following packages installed and available on your system:
Package |
Reason Needed |
|---|---|
Python 3.10 or later |
Needed to run Cobra |
Git |
Needed to acquire dependencies |
Glib2 |
Needed for LCM tools, to run Apps |
Java |
Needed for LCM tools, to run Apps |
Tkinter |
Needed for plotting filter results |
Ubuntu 22.04 users can use the following command to install the above packages:
sudo apt update && sudo apt install python3 python3-venv git libglib2.0-dev default-jre python3-tk
Users of other operating systems will need to install the above packages using their operating system’s package manager.
Cloning pntOS-Python
Next, download the pntOS-Python project onto your machine. While there are several approaches to do so, we suggest
you clone the pntos-python Git repository using:
git clone https://github.com/is4s/pntOS-Python.git
Finally, you are now ready to set up your Python environment in the next section.
Python Environment Setup
This project supports two workflows:
pip: the traditional Python package manager.
uv: a modern, faster, all-in-one alternative to pip.
If you are new to Python development, it is recommended that you use the pip workflow. Choose your preferred approach below:
We will begin by creating and entering a clean Python virtual environment (venv). We can create the virtual environment in the
.venv folder by running the following command in the project root directory:
python3 -m venv .venv --prompt pntos-python
Next, enter the virtual environment. The steps to do this vary depending on your shell:
source .venv/bin/activate
source .venv/bin/activate.fish
Your shell should now be inside the virtual environment. It is recommended that you upgrade your pip to the latest:
pip install --upgrade pip
Now we’re ready to install pntOS-Python. In the project root directory, run:
pip install -v -r requirements.txt
Note
This command may take a while to run. It is downloading example data, which may take a lot of bandwidth.
First, ensure you have uv installed. If you don’t have it yet, you can install it by following the instructions at https://docs.astral.sh/uv/getting-started/installation/.
Create a virtual environment using uv in the project root directory and import python dependencies in one step:
uv sync
Note
This command may take a while to run. It is downloading example data, which may take a lot of bandwidth.
Next, enter the virtual environment:
source .venv/bin/activate
source .venv/bin/activate.fish
Reference
For more information on this approach in the context of pntOS-Python, see the UV development process documentation.
If successful, you are ready to move on to Testing Your Installation. If not, please see Errata for troubleshooting help.
Testing Your Installation
Simply run the following command to verify that installation was successful:
python util/test_installation.py
If successful, you should see the following output:
Installation successful!
Congratulations, you are ready to start using Cobra! Your next steps are to try running a sample Cobra app, or start the tutorial on how Cobra works. If you’d like to try running a sample app, you should head over to running your first app. If you’d like to learn more about how Cobra works first, head over to the introduction to Cobra.
Errata & Troubleshooting
This section lists some potential failures you may encounter and how to resolve them.