Skip to main content

​
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.
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. 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: 
curl -LsSf https://astral.sh/uv/install.sh | sh

​
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:
PackageVersionPurpose
fastapi≥0.129.0Web framework for the server
python-multipart≥0.0.22Multipart form parsing for image uploads
typer≥0.23.1CLI framework
uvicorn[standard]≥0.40.0ASGI server
portalocker≥3.0.0Cross-platform file locking
watchdog≥6.0.0File system monitoring
websockets≥16.0WebSocket 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

Build docs developers (and LLMs) love

Get started for freeTalk to us