Skip to content

Installation

This guide covers different methods to install plowman.

Requirements

  • Python >= 3.10 (Python 3.14 preferred)

We recommend using uv for installing plowman as it provides an isolated environment for the package, preventing any dependency conflicts.

$ uv tool install --python 3.14 plowman

Verify the installation:

$ plm --version
plowman 0.3.1

Why uv?

  • Fast package installation and resolution
  • Isolated tool environments
  • Automatic Python version management
  • No dependency conflicts with system packages

Using pip

You can install plowman using pip if you prefer:

$ pip install plowman

Or with a specific Python version:

$ python3.14 -m pip install plowman

Verify the installation:

$ plm --version
plowman 0.3.1

Virtual Environment

For better isolation, consider using a virtual environment:

$ python3.14 -m venv ~/.venvs/plowman
$ source ~/.venvs/plowman/bin/activate
$ pip install plowman

Add the virtual environment's bin directory to your PATH to use plm globally:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.venvs/plowman/bin:$PATH"

From Source

Install directly from the GitHub repository:

$ git clone https://github.com/spapanik/plowman.git
$ cd plowman
$ pip install .

This method is useful if you want to:

  • Install a specific commit or branch
  • Test unreleased features
  • Contribute to development

Install Specific Version

$ git clone https://github.com/spapanik/plowman.git
$ cd plowman
$ git checkout v0.3.1
$ pip install .

Development Installation

If you want to contribute to plowman or modify it, install it in editable mode with development dependencies:

$ git clone https://github.com/spapanik/plowman.git
$ cd plowman
$ pip install -e ".[dev]"

This installs:

  • plowman in editable mode (changes to source code take effect immediately)
  • Testing tools (pytest, pytest-cov)
  • Linting tools (ruff, mypy, ty)
  • Documentation tools (mkdocs, mkdocs-material)
  • Development utilities (ipython, ptpython, ipdb)

Running Tests

After development installation, run the test suite:

$ pytest

Run with coverage:

$ pytest --cov=src/plowman

Code Quality Checks

Run linting:

$ ruff check src/ tests/
$ mypy src/

Platform-Specific Notes

macOS

On macOS, you may need to install Python first:

$ brew install python@3.14

Then install plowman:

$ uv tool install --python 3.14 plowman

Linux

Most Linux distributions include Python. Ensure you have Python 3.10+:

$ python3 --version
Python 3.10.12

If your distribution has an older Python, consider using pyenv or installing from source.

Windows

plowman is designed for Unix-like systems and manages dotfiles in your home directory. While it may work on Windows with WSL (Windows Subsystem for Linux), it's primarily intended for:

  • Linux
  • macOS
  • Other Unix-like systems

Troubleshooting Installation

Command Not Found

If plm is not found after installation:

With uv:

$ which plm

If not found, ensure uv's bin directory is in your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

With pip:

$ which plm

Check that the Python bin directory is in your PATH:

# For user installations
export PATH="$HOME/.local/bin:$PATH"

# For virtual environments
source ~/.venvs/plowman/bin/activate

Permission Errors

If you get permission errors with pip:

$ pip install --user plowman

Or use a virtual environment (recommended).

Python Version Issues

If you get errors about Python version:

$ python3 --version

Ensure you have Python 3.10 or higher. If not:

Using pyenv:

$ pyenv install 3.14.0
$ pyenv global 3.14.0

Using deadsnakes PPA (Ubuntu):

$ sudo add-apt-repository ppa:deadsnakes/ppa
$ sudo apt update
$ sudo apt install python3.14

Dependency Conflicts

If you encounter dependency conflicts:

Use uv (recommended):

$ uv tool install plowman

uv handles dependency isolation automatically.

Or use a virtual environment:

$ python3.14 -m venv ~/.venvs/plowman
$ source ~/.venvs/plowman/bin/activate
$ pip install plowman

Next Steps

After installation:

  1. Create your configuration: Configuration Guide
  2. Follow the tutorial: Tutorial
  3. Read the usage guide: Usage Guide

Verify your installation works:

$ plm --version
plowman 0.3.1

$ plm sow --help
usage: plm sow [-h] [-v] [-n]