> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/microsoft/markitdown/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with MarkItDown in minutes

## Overview

This guide will help you install MarkItDown and convert your first document to Markdown using both the command-line interface and Python API.

<Note>
  **Prerequisites**: Python 3.10 or higher. We recommend using a virtual environment to avoid dependency conflicts.
</Note>

## Installation

Install MarkItDown with all optional dependencies for full format support:

```bash theme={null}
pip install 'markitdown[all]'
```

<Tip>
  For specific format support, see the [detailed installation guide](/installation) to install only the dependencies you need.
</Tip>

## CLI quickstart

The command-line interface is the fastest way to convert documents.

<Steps>
  <Step title="Convert a file to Markdown">
    Use the `markitdown` command with any supported file:

    ```bash theme={null}
    markitdown document.pdf > output.md
    ```

    Or specify the output file with the `-o` flag:

    ```bash theme={null}
    markitdown document.pdf -o output.md
    ```
  </Step>

  <Step title="Convert from stdin">
    You can pipe content directly to MarkItDown:

    ```bash theme={null}
    cat presentation.pptx | markitdown > slides.md
    ```

    Or use input redirection:

    ```bash theme={null}
    markitdown < spreadsheet.xlsx > data.md
    ```
  </Step>

  <Step title="View the output">
    Open the output file to see your converted Markdown:

    ```bash theme={null}
    cat output.md
    ```
  </Step>
</Steps>

### CLI examples

<CodeGroup>
  ```bash PDF conversion theme={null}
  markitdown report.pdf -o report.md
  ```

  ```bash Excel to Markdown theme={null}
  markitdown data.xlsx > data.md
  ```

  ```bash PowerPoint slides theme={null}
  markitdown presentation.pptx -o slides.md
  ```

  ```bash Web page theme={null}
  markitdown https://example.com/article > article.md
  ```

  ```bash YouTube video theme={null}
  markitdown https://youtube.com/watch?v=VIDEO_ID > transcript.md
  ```
</CodeGroup>

## Python API quickstart

Integrate MarkItDown into your Python applications for programmatic document conversion.

<Steps>
  <Step title="Import and initialize">
    ```python theme={null}
    from markitdown import MarkItDown

    # Initialize with default settings
    md = MarkItDown()
    ```
  </Step>

  <Step title="Convert a file">
    ```python theme={null}
    # Convert a local file
    result = md.convert("document.pdf")

    # Access the Markdown content
    print(result.text_content)

    # Access the document title (if available)
    if result.title:
        print(f"Title: {result.title}")
    ```
  </Step>

  <Step title="Save the output">
    ```python theme={null}
    # Write to a file
    with open("output.md", "w", encoding="utf-8") as f:
        f.write(result.markdown)
    ```
  </Step>
</Steps>

### Python API examples

<CodeGroup>
  ```python Convert local file theme={null}
  from markitdown import MarkItDown

  md = MarkItDown()
  result = md.convert("report.pdf")
  print(result.text_content)
  ```

  ```python Convert from URL theme={null}
  from markitdown import MarkItDown

  md = MarkItDown()
  result = md.convert("https://example.com/document.pdf")
  print(result.text_content)
  ```

  ```python Convert Excel file theme={null}
  from markitdown import MarkItDown

  md = MarkItDown()
  result = md.convert("spreadsheet.xlsx")
  print(result.text_content)
  ```

  ```python Convert with LLM descriptions theme={null}
  from markitdown import MarkItDown
  from openai import OpenAI

  client = OpenAI()
  md = MarkItDown(
      llm_client=client,
      llm_model="gpt-4o"
  )

  # Images will be described by GPT-4o
  result = md.convert("image.jpg")
  print(result.text_content)
  ```

  ```python Convert from binary stream theme={null}
  from markitdown import MarkItDown
  import io

  md = MarkItDown()

  with open("document.pdf", "rb") as f:
      result = md.convert_stream(f)
      print(result.text_content)
  ```
</CodeGroup>

## Advanced usage

### Using LLM for image descriptions

Enhance image and PowerPoint conversions with AI-generated descriptions:

```python theme={null}
from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="Describe this image in detail for a technical audience."
)

result = md.convert("presentation.pptx")
print(result.text_content)
```

### Azure Document Intelligence

Use Microsoft's Document Intelligence for superior PDF processing:

<CodeGroup>
  ```bash CLI with Document Intelligence theme={null}
  markitdown document.pdf \
    -d \
    -e "https://YOUR_ENDPOINT.cognitiveservices.azure.com/" \
    -o output.md
  ```

  ```python Python with Document Intelligence theme={null}
  from markitdown import MarkItDown

  md = MarkItDown(
      docintel_endpoint="https://YOUR_ENDPOINT.cognitiveservices.azure.com/"
  )

  result = md.convert("document.pdf")
  print(result.text_content)
  ```
</CodeGroup>

<Note>
  Learn how to set up an Azure Document Intelligence Resource in the [Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/how-to-guides/create-document-intelligence-resource).
</Note>

### Using plugins

MarkItDown supports third-party plugins for extended functionality:

```bash theme={null}
# List installed plugins
markitdown --list-plugins

# Use plugins when converting
markitdown --use-plugins document.xyz -o output.md
```

To find available plugins, search GitHub for the hashtag `#markitdown-plugin`.

## Next steps

<CardGroup cols={2}>
  <Card title="Installation guide" icon="download" href="/installation">
    Learn about virtual environments and selective dependency installation
  </Card>

  <Card title="Python API reference" icon="code" href="/api/markitdown">
    Explore the complete API documentation
  </Card>

  <Card title="CLI reference" icon="terminal" href="/guides/cli-usage">
    See all command-line options and flags
  </Card>

  <Card title="Converters" icon="arrows-turn-to-dots" href="/api/converters/overview">
    Deep dive into format-specific converters
  </Card>
</CardGroup>

## Common patterns

### Batch conversion

```python theme={null}
from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()
input_dir = Path("documents")
output_dir = Path("markdown")

for file_path in input_dir.glob("*.pdf"):
    result = md.convert(str(file_path))
    output_path = output_dir / f"{file_path.stem}.md"
    output_path.write_text(result.markdown, encoding="utf-8")
```

### Error handling

```python theme={null}
from markitdown import MarkItDown, FileConversionException, UnsupportedFormatException

md = MarkItDown()

try:
    result = md.convert("document.xyz")
    print(result.text_content)
except UnsupportedFormatException:
    print("This file format is not supported")
except FileConversionException as e:
    print(f"Conversion failed: {e}")
```

### Processing HTTP responses

```python theme={null}
from markitdown import MarkItDown
import requests

md = MarkItDown()
response = requests.get("https://example.com/document.pdf")
result = md.convert_response(response)
print(result.text_content)
```

<Tip>
  **Need help?** Check out the [API reference](/api/markitdown) for detailed documentation on all methods and parameters.
</Tip>