​
Python Development Environment Setup

This page takes you from zero tooling to the point where you can run any command in the Getting Started guide. In this document we will walk through:
  • Setting up your IDE, terminal, and GitHub account
  • Installing Python
  • Choosing and installing a Python package manager (we recommend uv)
  • Creating a Repository and Project Folder to run the code
  • Setting up a virtual environment
  • Installing MeshAgent

​
Step 0: Install an IDE, terminal, and create a GitHub account

If you don’t already have a code editor installed, download one of your choice, for example VS Code, Windsurf, or Cursor. You can also install a more sophisticated terminal like warp which makes development even easier. Creating a GitHub account will make it easier for you to manage your code projects. We recommend creating an account and installing the GitHub Command Line Interface (CLI) to make GitHub management seamless. Follow the installation instructions for the GitHub CLI based on your machine.

​
Step 1: Install Python 3.12+

​
Windows

  1. Download Python from python.org.
  2. Important: Check “Add Python to PATH” during the installer.
  3. Verify in your terminal:
python --version
# → Python 3.12.x

​
macOS

Open your terminal and run the following to install python and verify the version 
brew install python@3.12
python3 -V

​
Linux

Most distros already ship a recent python version but if not run 
sudo apt-get install python3.12 python3.12-venv

​
Step 2: Choose your Python package manager

You can either use pip or uv as your Python package manager. Pip is the classic package manager, uv is a newer, faster drop-in replacement for pip. We recommend using uv since it makes package management easier. Verify the uv installation instructions for your machine on the astral website. You will likely run: 
curl -LsSf https://astral.sh/uv/install.sh | sh
Verify uv is installed correctly: 
uv --version

​
Using pip (alternative)

If you prefer to use pip, it should already be installed with Python. Verify it’s working: 
pip --version

​
Step 3: Create a repository and / or project folder

If you have a GitHub account, create a repository and then clone it to your machine:
  1. Create a repository on the GitHub website and fill in the appropriate details
  2. Once created, you’ll see a green “Code” button - click it
  3. Click the “GitHub CLI” tab (assuming you set up the GitHub CLI) and copy the command
  4. It will look like gh repo clone YOUR_REPO_NAME
  5. Paste this into your terminal to clone the repository
gh repo clone YOUR_REPO_NAME
cd YOUR_REPO_NAME

​
Option B: Local Folder Only

If you don’t have a GitHub account, create a new project folder where we’ll run the code samples: 
mkdir meshagent-getting-started
cd meshagent-getting-started

​
Step 4: Create your virtual environment

Virtual environments are important because they isolate your project dependencies from your system Python installation. This prevents version conflicts between different projects and keeps your system clean. In your terminal, inside the project folder, run the following commands to create your virtual environment based on the package manager you are using: 
uv init # only run this the first time you are creating a project 
uv venv # create the virtual environment (only run the first time)
Now activate the virtual environment (you will do this every time you cd into the project folder where you’re running your code) 
source .venv/bin/activate
You’ll know your virtual environment is active when you see .venv at the beginning of your terminal prompt.

​
Step 5: Install MeshAgent

Now that you have your virtual environment setup you can install MeshAgent! 
uv add 'meshagent[all]' # use quotes since we are installing all of the packages
Note: Any shell that does glob-expansion (zsh, fish, PowerShell) treats the square brackets as a wildcard unless they’re quoted or back-escaped, this is why you need to put quotes around the meshagent[all] install command. Installing meshagent[all] is beneficial because you will get all of the python libraries associated with MeshAgent. If you are installing individual packages with Python you do not need to run the install command with quotes. For example, if you only wanted to install one of the MeshAgent libraries, like the MeshAgent CLI, you would run the command like this: 
uv add meshagent-cli
Note: Inside an activated virtual-env pip already points to the right interpreter, so pip or pip3 both work. Outside a venv you may need to run pip3 to avoid Python 2 leftovers.

​
Next Steps

Congratulations! You now have everything set up to run the examples in the Getting Started guide.

​
Important Reminders

  • Always activate your virtual environment before working on your project:
source .venv/bin/activate
  • If using uv, you can use uv run python your_script.py to automatically use the virtual environment. If your virtual environment is already activated you can also just run python your_script.py.
  • Keep your virtual environment activated while following the Getting Started guide

​
Troubleshooting Common Issues

  • Python not found: Make sure Python was added to your PATH during installation (Windows) or use python3 instead of python (macOS/Linux).
  • Permission errors: On macOS/Linux, you might need to restart your terminal after installing uv, or run source ~/.bashrc or source ~/.zshrc.
  • Virtual environment not activating: Make sure you’re in the correct project directory when running the activation commands.