Installation

Install Markdown-OS using pip or uv package manager. Supports Python 3.11+.

Installation

Markdown-OS is distributed as a Python package on PyPI. You can install it using pip or the modern uv package manager.

Requirements

Python Version

Python 3.11 or higher (3.11, 3.12, 3.13 tested)

Operating System

Linux, macOS, or Windows (with POSIX compatibility notes)

File locking uses POSIX fcntl and is optimized for Linux/macOS. Windows users may need WSL for full compatibility.

Install with pip

The standard Python package installer:

pip install markdown-os

This installs the markdown-os CLI command globally in your Python environment.

Installing with pip in your global Python environment may cause dependency conflicts. Consider using a virtual environment or pipx for isolated installation.

Using pipx (Recommended)

For isolated CLI tool installation:

pipx install markdown-os

This creates an isolated environment and adds the command to your PATH without affecting other Python packages.

Install with uv (Recommended)

uv is a fast, modern Python package manager. It’s the recommended installation method for Markdown-OS.

Install uv

If you don’t have uv installed:

macOS/Linux

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

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Install Markdown-OS

Use uv’s tool installer for clean, isolated installation:

uv tool install markdown-os

This creates an isolated environment and makes the markdown-os command available globally.

The uv tool install command is similar to pipx install but uses uv’s faster resolver and installer.

Verify Installation

Check that Markdown-OS is installed correctly:

markdown-os --help

You should see output like:

Usage: markdown-os [OPTIONS] COMMAND [ARGS]...

  Open and edit markdown files in a local browser UI.

Options:
  --help  Show this message and exit.

Commands:
  example  Generate a showcase markdown file that demonstrates...
  open     Start a local web editor for a markdown file or...

Upgrading

Upgrade with pip

pip install --upgrade markdown-os

Upgrade with uv

uv tool upgrade markdown-os

Check the GitHub releases or PyPI page for the latest version.

Uninstalling

Uninstall with pip

pip uninstall markdown-os

Uninstall with uv

uv tool uninstall markdown-os

Dependencies

Markdown-OS automatically installs the following Python dependencies:

Package	Version	Purpose
fastapi	≥0.129.0	Web framework for the server
python-multipart	≥0.0.22	Multipart form parsing for image uploads
typer	≥0.23.1	CLI framework
uvicorn[standard]	≥0.40.0	ASGI server
portalocker	≥3.0.0	Cross-platform file locking
watchdog	≥6.0.0	File system monitoring
websockets	≥16.0	WebSocket support for live sync

These are handled automatically during installation.

Development Installation

If you want to contribute to Markdown-OS or run the development version:

1. Clone the repository

   git clone https://github.com/elena-cabrera/markdown-os.git
   cd markdown-os
   
2. Install uv (if needed)

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

   uv sync
   

   This reads pyproject.toml and installs all dependencies including dev tools.

4. Run from source

   uv run markdown-os open ./example.md
   

Running Tests

The project includes 61 async-compatible tests using pytest:

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_cli.py

# Run single test
uv run pytest tests/test_cli.py::test_validate_markdown_file_returns_resolved_path

Troubleshooting

Command Not Found

If markdown-os is not found after installation:

1. Check your PATH: Ensure pip/uv’s bin directory is in your PATH
2. Reinstall: Try uninstalling and reinstalling
3. Use full path: Try python -m markdown_os.cli instead

Python Version Errors

Markdown-OS requires Python 3.11+. Check your version:

python --version

If you have multiple Python versions:

python3.11 -m pip install markdown-os

Or with uv:

uv python install 3.13
uv tool install markdown-os

Import Errors

If you see import errors, ensure all dependencies are installed:

pip install --force-reinstall markdown-os

Port Already in Use

Markdown-OS defaults to port 8000 but auto-increments if occupied. Watch the CLI output for the actual URL:

Opening file /path/to/notes.md at http://127.0.0.1:8001

You can also specify a custom port:

markdown-os open notes.md --port 9000

Platform-Specific Notes

macOS

macOS users should have no issues. The app opens your default browser automatically.

Linux

Linux users may see harmless dbus warnings when the browser auto-opens:

No GSettings schemas are installed on the system

These can be ignored. The server still works perfectly.

Windows

Windows users should use WSL (Windows Subsystem for Linux) for best compatibility due to file locking differences:

wsl --install

Then install and run Markdown-OS from within WSL.

Cloud VMs and Remote Access

If running on a cloud VM or remote server, bind to 0.0.0.0 to allow external access:

markdown-os open notes.md --host 0.0.0.0 --port 8000

Binding to 0.0.0.0 exposes your files to the network without authentication. Only use this on trusted networks or with proper firewall rules.

Next Steps

Quick Start Guide

Learn how to use Markdown-OS with real examples