Jak zamienić pliki PDF i Word na tekst dla AI: MarkItDown od Microsoftu

Więcej instrukcji znajdziesz w dokumentacji Ailoot.

Czym jest MarkItDown i do czego służy?#

Wysyłasz AI umowę, raport albo eksport księgowy, a otrzymujesz odpowiedź, która nie ma z dokumentem nic wspólnego. Zwykle winny nie jest model. Plik zawiera format: Word to archiwum ze znacznikami, Excel to arkusz z powiązaniami między komórkami, a PDF to zestaw znaków o współrzędnych na stronie. Model pracuje z tekstem, więc ktoś musi ten tekst wyodrębnić.

Właśnie tym zajmuje się MarkItDown. Repozytorium znajduje się pod adresem github.com/microsoft/markitdown i jest objęte licencją MIT, więc można z niego korzystać bez ograniczeń. Na dzień 18 sierpnia 2026 r. ma 174,412 gwiazdek i 12,756 forków; najnowsze wydanie, 0.1.7, ukazało się 29 lipca. Projekt jest aktywny, choć jego uwaga przesunęła się z rozwoju na utrzymanie: ma 481 otwartych pull requestów wobec 183 scalonych w całej historii.

Twórcy opisują jego przeznaczenie tak:

Kolejne zdanie opisu wyjaśnia połowę zastrzeżeń, jakie ludzie mają wobec tego narzędzia:

Wynik to surowiec dla modelu. Nie będzie pięknym dokumentem — projekt mówi o tym wprost, już w pierwszej sekcji.

Opis bezpośrednio wyjaśnia, dlaczego używa Markdowna: wiodące modele już „mówią” tym językiem znaczników i włączają go do odpowiedzi bez proszenia, bo podczas treningu widziały go w ogromnych ilościach. Znaczniki są też zwięzłe: trzy znaki hash dla nagłówka zamiast kilkunastu wierszy metadanych.

Czym MarkItDown różni się od zwykłego konwertera?#

Różnicę dobrze widać na przykładzie. Weź folder z dwudziestoma PDF-ami i spróbuj przetworzyć je w pandoc. Nie uda się: pandoc potrafi tworzyć PDF-y jako wynik, ale nie potrafi ich odczytywać jako danych wejściowych. A sytuacja „mam stos dokumentów, daj je modelowi” jest najczęstsza.

Twórcy MarkItDown porównują swoje narzędzie z textract — biblioteką, która po prostu wyodrębnia tekst z różnych źródeł. Różnica polega na tym, że MarkItDown stara się zachować strukturę: nagłówki, listy, tabele i linki.

Praktyczny wniosek jest prosty. Jeśli chcesz zamienić artykuł na układ do publikacji, użyj pandoc. Jeśli chcesz, by AI zrozumiała dwadzieścia umów, użyj MarkItDown.

Jak zainstalować MarkItDown, żeby nie dostać pierwszego wydania?#

Najpierw właściwe polecenie, potem wyjaśnienie, dlaczego jest właściwe.

1. Sprawdź wersję Pythona

   Python 3.12 jest najbardziej niezawodny: najnowszy MarkItDown instaluje się w każdym przetestowanym środowisku z tą wersją. Polecenie python3 --version pokazuje, którą wersję masz. Na Macach z procesorem Intel lub starszym macOS Python 3.13 i 3.14 mogą po cichu obniżyć wersję; Python 3.15 nie jest jeszcze obsługiwany, jak wyjaśniono poniżej.

2. Zainstaluj, podając formaty

   Uruchom pip install 'markitdown[pdf,docx,xlsx,pptx]'. Cudzysłowy są wymagane, bo inaczej powłoka zinterpretuje nawiasy kwadratowe. Na Macu z procesorem Intel dodaj flagę --prefer-binary po install.

3. Od razu sprawdź, czy instalacja się powiodła

   Uruchom markitdown --version. Odpowiedź powinna brzmieć markitdown 0.1.8 lub później. Niższy numer oznacza obniżenie wersji podczas instalacji; ta sekcja wyjaśnia dlaczego.

pip install 'markitdown[pdf,docx,xlsx,pptx]'
markitdown --version

Opis projektu podaje pip install 'markitdown[all]' jako główne polecenie — instaluje ono wszystko naraz. 28 września 2026 r., tydzień po wydaniu 0.1.8, uruchomiono cztery warianty w czystych środowiskach na Macu z Apple Silicon i Pythonem 3.14.6 oraz 3.12.12:

Wszystkie osiem instalacji zakończyło się komunikatem „Successfully installed”, a markitdown --version zwróciło 0.1.8 w każdym przypadku. W sierpniu, gdy najnowszym wydaniem było 0.1.7, trzecie polecenie w Pythonie 3.14 zainstalowało 0.0.2, wydane 8 marca 2025 r. — drugie wydanie w historii projektu. Obecnie jest jedenaście stabilnych wydań, od 0.0.1 do 0.1.8, oraz dwadzieścia sześć, jeśli uwzględnić wersje przedpremierowe.

Przyczyną był łańcuch zależności. W 0.1.7 dodatkowy pakiet [all] pobiera bibliotekę napisów YouTube z określonej serii wydań, a wszystkie wydania z tej serii deklarują niezgodność z Pythonem 3.14. Instalator je odrzuca i, ponieważ nie przypięto wersji, cofa się przez kolejne wersje MarkItDown, aż znajdzie taką, którą można zainstalować. Znajduje 0.0.2 i instaluje ją, umieszczając na komputerze wydanie sprzed półtora roku. W 0.1.8 wymaganie dotyczące biblioteki napisów podniesiono do serii działającej z 3.14, więc obniżanie wersji zatrzymało się na tym etapie.

Mechanizm nadal istnieje. Jeśli instalator nie znajdzie jednego wymaganego składnika dla danego systemu, po cichu cofnie się do 0.0.2 w ten sam sposób. W nowszych wersjach tym składnikiem jest silnik onnxruntime używany przez wykrywacz typu pliku. Na Macu jest on kompilowany w następujący sposób: dla Pythona 3.12 — macOS 11 i nowszy; dla 3.13 — macOS 13; dla 3.14 — tylko Apple Silicon z macOS 14 lub nowszym. Jeśli twój Mac nie spełnia tych wymagań, nawet podstawowe polecenie pip install markitdown zainstaluje 0.0.2. Test na Macu z procesorem Intel, Pythonem 3.14 i Rosettą dał dokładnie taki wynik: „Successfully installed”, bez ostrzeżeń, a wewnątrz — 0.0.2.

Maki z procesorem Intel mają jeszcze jedną komplikację. Od czerwca 2026 r. biblioteka cryptography pobierana do odczytu PDF-ów jest wydawana bez gotowej wersji dla tego procesora, więc instalator próbuje skompilować ją ze źródeł. Dodaj do polecenia flagę --prefer-binary, a użyje poprzedniej wersji z gotowym pakietem. W teście na Pythonie 3.13 na Intelu zainstalowano w ten sposób 0.1.8 i PDF otworzył się poprawnie. Flaga instaluje cryptography 48.0.1, która ma trzy znane luki: w deszyfrowaniu PKCS#7 i weryfikacji łańcucha certyfikatów. MarkItDown używa jej tylko do odszyfrowywania zaszyfrowanych PDF-ów, a odczyt dokumentów nie korzysta z tych części.

W Pythonie 3.15 obniżenie wersji następuje z dwóch powodów. Wersja 0.1.8 deklaruje obsługę wyłącznie od 3.10 do 3.14, a silnik dla 3.15 jeszcze nie istnieje. Rozwiązanie instalatora dla 3.15 to potwierdza: zarówno podstawowe polecenie, jak i polecenie z formatami instalują to samo 0.0.2.

Ostrzeżenie o obniżeniu wersji wygląda tak — po jednym wierszu dla każdego dodatku w poleceniu:

WARNING: markitdown 0.0.2 does not provide the extra 'all'

Wiersz ginie wśród dziesiątek wierszy pobierania i nie mówi nic o wersji, która została podstawiona. Przy podstawowym poleceniu bez dodatków nie ma nawet ostrzeżenia. Raport końcowy jest radosny: „Successfully installed”.

Instalacja bez dodatków też nie jest rozwiązaniem. Podstawowy pakiet się instaluje, ale nie potrafi otwierać PDF-ów:

PdfConverter recognized the input as a potential .pdf file, but the
dependencies needed to read .pdf files have not been installed. To resolve
this error, include the optional dependency [pdf] or [all] when installing
MarkItDown. For example:

* pip install 'markitdown[pdf]'
* pip install 'markitdown[all]'

Samo narzędzie zaleca [all] i w wersji 0.1.8 ta rada znów działa w Pythonie 3.14 i 3.12. Mimo to lepiej wymieniać formaty z nazwy: [all] dodaje około piętnastu kolejnych pakietów i około 55 megabajtów, w tym przedpremierową bibliotekę Azure oraz łańcuch zależności YouTube, który już raz popsuł instalację.

Instalator sam obsługuje przedpremierową wersję Azure. Zwykle pip pomija takie wersje, ale tutaj wymaganie jawnie wskazuje wersję przedpremierową, więc ją instaluje. Przetestowano cztery wersje pip, od 23.2 do 26.2, w Pythonie 3.12; wszystkie wybierają 0.1.8.

W sierpniu ponowna instalacja w innym czystym środowisku dała ten sam wynik: 0.0.2 i słowo „Successfully”.

Warto zawczasu znać kilka praktycznych szczegółów.

Pakiet jest dość duży: podstawowa instalacja zajmuje 143 megabajty, a instalacja z czterema formatami — 303. Najcięższy składnik, zajmujący 81 megabajtów, to wykrywacz typu pliku, pobierany nawet przy podstawowej instalacji. Na laptopie nie ma to znaczenia, ale ma je w funkcji chmurowej z limitem rozmiaru.

Nie licz na kopie lustrzane jako rozwiązanie awaryjne. Przetestowana kopia udostępniała indeks i pliki MarkItDown były dostępne, ale brakowało jednej wymaganej zależności, więc instalacja nie powiodła się ani w Pythonie 3.14, ani 3.12.

Instalacja to drobiazg w porównaniu z głównym problemem. Znacznie częściej AI generuje bzdury, bo do jej okna kontekstowego trafiło coś niewłaściwego albo niewłaściwa reprezentacja danych. Umiejętność decydowania, co przekazać modelowi przed zadaniem, nazywa się inżynierią kontekstu, a przygotowanie dokumentów jest jej częścią.

Jak zamienić pierwszy dokument na tekst?#

Najkrótsza opcja:

markitdown dogovor.docx

Tekst wyświetli się w terminalu. Są dwa sposoby, by zapisać go do pliku:

markitdown dogovor.docx -o dogovor.md
markitdown dogovor.docx > dogovor.md

Na Macu i Linuksie różnica jest znikoma, ale ma znaczenie w Windowsie: przekierowanie przez > może spowodować awarię programu, gdy wynik zawiera cyrylicę.

Można przekazać plik jako strumień; w takim przypadku przydatna jest wskazówka dotycząca rozszerzenia:

cat dogovor.docx | markitdown -x docx

Oto główne flagi z pomocy wersji 0.1.8:

Ta sama pomoc wymienia jeszcze trzy przydatne flagi, z których każdą przetestowano: --list-plugins wyświetla zainstalowane wtyczki, -p włącza je dla danego uruchomienia, a --keep-data-uris zachowuje w wyniku obrazy osadzone w dokumencie (domyślnie są przycinane). Pozostałe ustawienia dotyczą usług chmurowych Microsoftu.

Wrapper w Pythonie ma trzy wiersze:

from markitdown import MarkItDown

md = MarkItDown()
print(md.convert("ostatki.xlsx").text_content)

To samo wywołanie przyjmuje adres URL. Prosta strona zwróciła czysty tekst o długości 167 znaków, zawierający nagłówek i link, bez menu i stopki:

r = md.convert("https://example.com")

Jakie formaty obsługuje MarkItDown i co to naprawdę oznacza?#

Tabela podsumowuje deklaracje i ich praktyczne znaczenie.

Trzy elementy omówmy dokładniej.

Obrazy. Opis zawiera słowo OCR, więc użytkownicy oczekują, że program odczyta tekst ze zdjęcia. Tak się nie dzieje. Program odczytuje metadane za pomocą osobnego narzędzia exiftool, a po podłączeniu modelu wizyjnego własnym kluczem może wysłać mu obraz do opisania.

Dźwięk. Transkrypcja mowy jest dostępna, ale język nie jest przekazywany, a silnik domyślnie oczekuje angielskiego. Narzędzie wywołuje też nieoficjalny, bezpłatny punkt końcowy Google, ograniczony do około pięćdziesięciu żądań dziennie na klucz.

Archiwa. Program rozpakowuje pliki ZIP, przechodzi przez zawarte w nich pliki i łączy wyniki. Jeśli nie potrafi przetworzyć pliku, błąd zostaje przechwycony i zignorowany. Plik po prostu nie pojawi się w wyniku i nie będzie o tym wiadomo.

Co dzieje się z dokumentami zawierającymi cyrylicę?#

Poniższe pliki utworzono specjalnie do testów; zawarte w nich dane są fikcyjne.

Arkusz inwentaryzacyjny w Excelu również wyszedł czysto, a nazwa arkusza stała się nagłówkiem:

## Stock
| Item | In stock | Reserved | Available |
| --- | --- | --- | --- |
| Coffee beans, kg | 420 | 38 | 382 |
| Loose-leaf tea, kg | 180 | 52 | 128 |

Prezentacja zmieniła się w tekst, z numerami slajdów pokazanymi jako adnotacje i tytułami slajdów zamienionymi na nagłówki. Cyrylica również zachowała się bez zmian. Ogólne twierdzenie, że „MarkItDown nie rozumie cyrylicy”, jest fałszywe.

Teraz trzy miejsca, w których rzeczywiście pojawiają się problemy.

CSV ze średnikami. Dwa identyczne eksporty faktur przetworzono w celu porównania. Plik z przecinkami dał prawidłową tabelę z czterema kolumnami. W pliku ze średnikami cały wiersz trafił do jednej komórki.

Cały wiersz znalazł się w jednej komórce. Kodowanie rozpoznano prawidłowo i nie wystąpił żaden błąd; flaga -c nie pomaga. Model otrzyma tę tabelę i nie zrozumie, która wartość oznacza kwotę, a która status. Wyeksportuj plik ponownie z jawnym separatorem przecinkowym i właściwym kodowaniem, zachowując oryginał bez zmian. Nie zastępuj średników globalnie: separatory w tekście ujętym w cudzysłów i przecinki dziesiętne mogą być częścią wartości. Jeśli ponowny eksport jest niemożliwy, odczytaj oryginał parserem CSV z jego rzeczywistym separatorem i zapisz nowy CSV narzędziem zachowującym cytowanie i wartości komórek. Przed analizą porównaj liczbę kolumn, wierszy i sumy kontrolne ze źródłowym eksportem.

Formatowanie walut w Excelu. Symbol waluty jest zapisany w ustawieniach wyświetlania komórki i nie trafia do samej wartości. Opiekunowie projektu potwierdzili przyczynę. Ma to znaczenie przy cenniku lub fakturze: model zobaczy liczby, ale nie będzie wiedział, jaką walutę oznaczają.

Konsola Windows. Przy plikach z niełacińskimi znakami program może ulec awarii.

Ślad błędu pokazuje kodowanie cp1251, czyli konsolę Windows. Sam dokument jest poprawnie przetwarzany; problemem jest wypisanie wyniku w oknie terminala. Istnieją więc dwa obejścia:

markitdown dogovor.docx -o dogovor.md
$env:PYTHONUTF8 = "1"; markitdown dogovor.docx > dogovor.md

Pierwsze całkowicie omija konsolę, a drugie sprawia, że Python zapisuje dane w UTF-8. Użytkownicy przesłali poprawki do samego narzędzia co najmniej sześć razy: część propozycji zamknięto bez scalenia, a pozostałe nadal pozostają otwarte. Trzeba więc zastosować obejście.

Czwarty objaw występuje w PDF-ach: zamiast liter pojawiają się ciągi takie jak (cid:1090). Oznacza to, że plik ma niestandardową tablicę czcionek i nie da się zdekodować jego znaków. Nie ma sensu przetwarzać takiego dokumentu w MarkItDown; potrzebne jest inne narzędzie.

Dlaczego PDF zamienia się w bałagan?#

Na potrzeby testu przetworzono dwukolumnowy artykuł naukowy o rozmiarze 2.16 megabajta. Kod wyjścia wyniósł zero; po 0.9 sekundy wynik zawierał 88,000 znaków, z których niemal wszystkie były bełkotem. Osiemdziesiąt osiem tysięcy znaków sprawia wrażenie, że wszystko się udało. Dopóki nie otworzysz pliku:

|     | Hybrid |          | OCR-LLM     |     | Framework  |
| --- | ------ | -------- | ----------- | --- | ---------- |
...
Informationextractionfromcopy-heavydoc-
5202 tcO 11  ]LC.sc[  1v83101.0152:viXra

Jednocześnie poszły nie tak trzy rzeczy. Układ dwukolumnowy zamienił się w tabele, których nie ma w artykule. Słowa zlały się bez spacji. Ostatni wiersz to pionowy panel boczny na stronie, wyodrębniony w odwrotnej kolejności.

Potem nastąpiła zabawna część. Okazało się, że testowany artykuł był właśnie pracą mierzącą MarkItDown i porównującą je z innymi narzędziami. Narzędzie zamieniło akapit opisujący własne pomiary na taki tekst:

cues. This name-matching error could be miti-  OCRpreprocessingoverhead(0.056s),whileDo-
gatedthroughpromptengineeringtoprovidemore  clingandMinerUadoptmorecomputationallyin-
explicit matching instructions or fine-tuning the  tensive strategies with OCR latencies of approxi-

Lewa i prawa kolumna są połączone wiersz po wierszu. Model, któremu podasz taki tekst, przeczyta połowę zdania z jednego akapitu i połowę z drugiego.

Przyczyna jest techniczna i prosta. Word jawnie zapisuje „to jest nagłówek” i „to jest komórka tabeli”. PDF zapisuje „to jest znak” i „oto jego współrzędne na stronie”. Odtworzenie struktury ze współrzędnych to osobne, trudne zadanie, a MarkItDown ledwie próbuje je wykonać. Kod źródłowy przetwarzania PDF-ów nie zawiera wykrywania nagłówków: jeśli strona nie zostanie rozpoznana jako formularz lub tabela, cały dokument przechodzi przez podstawowe wyodrębnianie tekstu.

Użytkownicy regularnie zgłaszają to w repozytorium projektu, również w przypadku artykułów naukowych i tabel.

Narzędzie nie znajduje w PDF-ach ani jednego nagłówka, dokładnie tak, jak pokazuje jego kod źródłowy.

W internecie krąży liczba „MarkItDown osiąga dokładność 82%”, ale bez jakiejkolwiek metodologii. Próba dotarcia do pierwotnego źródła nic nie daje: łańcuch linków kończy się na stronie, której nie można załadować. Nie można traktować tego jako pomiaru.

Co stanie się ze skanem umowy?#

To zachowanie jest groźniejsze od pozostałych, bo nie wygląda na awarię.

Na potrzeby testu utworzono PDF z obrazu zawierającego tekst — dokładnie takiego, jaki otrzymujesz po sfotografowaniu lub zeskanowaniu umowy. Uruchomienie powtórzono, by wykluczyć przypadek:

Zero znaków i zero błędów, dwa razy z rzędu. Kod wyjścia zero oznacza „wszystko przebiegło pomyślnie”, więc każdy skrypt sprawdzający powodzenie na podstawie kodu wyjścia uzna dokument za przetworzony. Następnie pusty wynik trafia do modelu, model nic nie widzi i zaczyna wymyślać odpowiedź z powietrza.

Istnieją dwa obejścia i oba są płatne. Pierwsze to flaga -d, która wysyła dokument do chmurowej usługi rozpoznawania Microsoftu; tekst pomocy do flagi wyraźnie wskazuje, że wymagany jest prawidłowy punkt końcowy usługi. Drugie to osobny pakiet dodatkowy, który wysyła strony do modelu wizyjnego z użyciem twojego klucza, więc płacisz dostawcy modelu za każdą stronę. Od kwietnia 2026 r. w otwartej dyskusji dotyczącej drugiej metody zgłaszano, że przetwarzana jest tylko pierwsza strona wielostronicowego skanu.

Możesz też uruchomić model rozpoznawania na własnym komputerze, ale to osobny projekt.

W przypadku pojedynczego dokumentu łatwiej go otworzyć i ręcznie skopiować tekst. Przy serii skanów potrzebujesz narzędzia z wbudowanym rozpoznawaniem.

Czy można po prostu przesłać plik do konwertera online?#

„MarkItDown online” to jedna z najczęstszych podpowiedzi w wyszukiwarce i istnieją strony, które oferują taką usługę. Oryginalne narzędzie Microsoftu w ogóle nie ma strony internetowej; jest dostępne wyłącznie jako program instalowany samodzielnie. Wszystko o podobnej nazwie, co otwiera się w przeglądarce, stworzył ktoś inny.

Możesz sprawdzić taką usługę w minutę: otwórz narzędzia deweloperskie na karcie żądań sieciowych, prześlij dowolny nieszkodliwy plik i zobacz, czy trafia on na serwer. Jeśli tak, twierdzenie o przetwarzaniu w przeglądarce jest fałszywe, niezależnie od tego, jak przekonująco przedstawiono je w FAQ.

Dlatego MarkItDown jest cenione tam, gdzie dokumentów nie wolno wysyłać poza organizację. W jednej z dyskusji ktoś opisał swoją sytuację: na służbowym laptopie zakazano instalowania dowolnych programów, ale biblioteki Pythona były dozwolone, a lokalne narzędzie okazało się jedyną dostępną opcją.

Ile MarkItDown naprawdę oszczędza?#

Plik Office to uporządkowane archiwum zawierające znaczniki. Jeśli rozpakujesz trzy pliki testowe i porównasz rozmiar części zawierającej treść z rozmiarem wyniku, otrzymasz takie wartości:

Pliki są małe; proporcje będą inne dla większych dokumentów i nie istnieje jedna uniwersalna wartość oszczędności. Gdy w artykułach porównawczych pojawiają się okrągłe liczby, zapytaj o metodologię.

Twórcy również mówią o oszczędnościach: opis projektu wyraźnie stwierdza, że konwencje Markdowna są bardzo oszczędne pod względem liczby znaków. To prawda, ale nie powinno być głównym argumentem za narzędziem. Różnica między „model dostał trzy tysiące znaków zamiast piętnastu tysięcy” a „model dostał jasną strukturę zamiast plątaniny” jest zupełnie innego rzędu. Pierwsze oszczędza pieniądze; drugie decyduje, czy odpowiedź będzie miała sens.

Jeśli martwi cię wykorzystanie kontekstu, omówiono je osobno: Dokąd trafiają tokeny w Claude i ile zawiera każdy plan.

Jak połączyć MarkItDown z Claude przez MCP?#

MCP to sposób na udostępnienie AI zewnętrznego narzędzia, z którego może korzystać samodzielnie. Przegląd mechanizmu i innych serwerów znajdziesz w recenzji serwerów MCP dla Claude Code.

Serwer MarkItDown udostępnia dokładnie jedno narzędzie: konwersję dokumentu na tekst. Przyjmuje lokalną ścieżkę do pliku, adres strony albo dane osadzone bezpośrednio w żądaniu.

Można połączyć go z Claude Code jednym poleceniem, przypinając wersję serwera. Potrzebny jest menedżer pakietów uv:

claude mcp add --scope user --env 'ORT_DISABLE_TELEMETRY=1' --env 'UV_PYTHON=3.12' --transport stdio markitdown -- uvx markitdown-mcp@0.0.1a7
claude mcp list

Odpowiedź na drugie polecenie powinna pokazać „Connected” przy markitdown. Pierwsze uruchomienie pobiera około siedemdziesięciu pakietów i trwa do minuty; później serwer uruchamia się w ciągu jednej do półtorej sekundy.

Poniższe zastrzeżenia zostały sprawdzone ręcznie.

Kompilację 0.0.1a7 wydano 14 września 2026 r. Wcześniej serwer tkwił na wersji 0.0.1a4 z maja 2025 r. przez ponad rok. Najnowszy numer wersji nadal oznacza wydanie przedpremierowe.

Nie zainstaluje się w każdym systemie z najnowszą wersją Pythona. Zależny od niego silnik onnxruntime jest dostępny dla Pythona 3.14 na Macu tylko na Apple Silicon z macOS 14 lub nowszym, dlatego instalacja nie powiedzie się na Macach z procesorem Intel oraz na macOS 13 lub starszym z Pythonem 3.14. Na Macu z Apple Silicon uruchomiono serwer w Pythonie 3.14, 3.13 i 3.12; we wszystkich trzech wersjach instalacja się powiodła. Polecenie używa UV_PYTHON=3.12: gotowe pakiety dla 3.12 są dostępne w Windowsie, Linuksie i na Macach z Apple Silicon, a jeśli nie masz tej wersji Pythona, uv ją pobierze. Także tu jest zastrzeżenie dla Maców z procesorem Intel: uv skompiluje bibliotekę cryptography ze źródeł, bo od czerwca 2026 r. nie ma dla Intela gotowego pakietu. Instalacja potrwa dłużej i może się nie powieść.

Wersja MarkItDown zainstalowana wewnątrz zależy od wersji uv. Od MarkItDown 0.1.6 dodatek [all] wymaga przedpremierowej biblioteki Azure: uv 0.12 i nowsze instaluje ją oraz najnowszy MarkItDown 0.1.8, a starsze wersje uv cofają się do 0.1.5. Sprawdź wersję uv poleceniem uv --version.

Dwie rzeczy są wysyłane poza komputer. Pierwsza to telemetria: na Macu i Linuksie silnik onnxruntime działający wewnątrz serwera domyślnie wysyła ją do Microsoftu. Zmienna ORT_DISABLE_TELEMETRY=1 w poleceniu ją wyłącza. W teście serwer łączył się z punktami końcowymi telemetrii Microsoftu, gdy zmienna nie była ustawiona. Po jej ustawieniu, podczas przetwarzania plików z dysku, nie było żadnych połączeń.

Druga rzecz to dźwięk. Serwer wysyła pliki WAV, MP3, M4A i MP4 do usługi rozpoznawania mowy Google w celu transkrypcji przez zwykłe HTTP, bez szyfrowania. Lepiej nie wysyłać przez niego nagrań rozmów z klientami.

Duży dokument się nie zmieści. W otwartej dyskusji opisano odpowiedź serwera o rozmiarze 51,000 tokenów, która przekroczyła limit 25,000 tokenów; narzędzie nie dzieli plików na fragmenty.

I kwestia bezpieczeństwa. Własna dokumentacja pakietu stwierdza wprost:

Innymi słowy, agent z tym narzędziem może odczytać wszystko, do czego ty masz dostęp. Jest to akceptowalne podczas pracy na własnym komputerze. Nie wolno wystawiać serwera publicznie ani udostępniać go niezaufanemu agentowi.

W codziennej pracy łatwiej uruchomić program poleceniem i umieścić wynikowy tekst w projekcie. Plik leży wtedy obok pozostałych materiałów, gdzie model może sam z niego korzystać.

Kiedy uczciwiej jest użyć innego narzędzia?#

Porównanie według zadań; liczba gwiazdek w GitHubie nie ma tu znaczenia:

Jest szczegół dotyczący Markera, który pomijają artykuły porównawcze. Od lipca 2026 r. sam kod jest objęty liberalną licencją, a wagi modeli — osobną licencją z progiem: użycie jest bezpłatne, jeśli przychody firmy nie przekroczyły pięciu milionów dolarów, a pozyskane finansowanie w poprzednim roku nie przekroczyło tej samej kwoty. Osobny zapis zabrania korzystania z narzędzia podmiotom budującym konkurencyjny produkt. Dla większości czytelników nie ma to znaczenia, ale rozwijająca się firma powinna przeczytać licencję przed wdrożeniem.

Z tego wynika praktyczny, czteroetapowy proces:

1. Przepuść wszystko przez MarkItDown — jest bezpłatne i natychmiastowe.
2. Otwórz wynik i sprawdź jego rozmiar.
3. Jeśli tekst ma sens, zadanie jest wykonane; nic więcej nie trzeba.
4. Jeśli wynik jest chaotyczny lub pusty, przetwórz ten konkretny plik cięższym narzędziem.

Dzięki temu ponosisz koszt czasu i złożoności tylko dla dokumentów, które tego wymagają.

Jak włączyć MarkItDown do swojego procesu pracy?#

Anthropic używa MarkItDown we własnych gotowych umiejętnościach pracy z plikami Office, a ich opisy jasno określają granicę, którą warto w całości przyjąć:

W tekście nie ma odwołań do komórek ani stron, dlatego nie można użyć go do wprowadzania zmian w pliku źródłowym. Oto trzy scenariusze.

Partia podobnych dokumentów — protokołów, faktur, formularzy, wniosków. Umieść je w folderze i przetwórz jednym wierszem:

for f in dokumenty/*.docx; do markitdown "$f" -o "text/$(basename "$f" .docx).md"; done

Następnie przekaż modelowi folder z plikami tekstowymi i poproś go o zebranie istotnych informacji w tabeli. Działa to z plikami cyfrowymi; skany się nie powiodą i od razu zauważysz je po zerowym rozmiarze.

Stałe materiały projektu — cenniki, wzory umów, zasady, opisy usług. Zamień je na tekst raz i umieść obok projektu. Model będzie mógł czytać je przy każdym żądaniu, więc nie trzeba za każdym razem załączać plików do rozmowy. Artykuł o przesyłaniu plików do Claude wyjaśnia, czym różni się to od przesłania pliku do czatu.

Eksport z systemu księgowego. Eksport z oprogramowania księgowego lub konta bankowego w Excelu zamienia się w tabelę w jedną trzecią sekundy, a model może na tej podstawie wykonywać obliczenia bez dodatkowych zabiegów. Sprawdź, czy CSV wyeksportowano lub odczytano z jego rzeczywistym separatorem, cytowaniem i kodowaniem, i porównaj wiersze, kolumny oraz sumy kontrolne przed przekazaniem modelowi. Nie normalizuj separatorów przez wyszukiwanie i zamianę. Zapisz też walutę jawnie: symbol istniejący wyłącznie w formatowaniu komórki Excel nie przetrwa ekstrakcji.

Przetwarzanie dużych PDF-ów w terminalu nie znajduje się na tej liście. To osobne zagadnienie dotyczące wykorzystania kontekstu, omówione w artykule o PDF-ach w Claude Code bez utraty tokenów. Jeśli dopiero konfigurujesz swoje środowisko pracy, zacznij od instalacji Claude Code.

Aby zacząć od razu, uruchom pip install 'markitdown[pdf,docx,xlsx,pptx]', przetwórz pierwszą znalezioną umowę w Wordzie i sprawdź rozmiar wyniku. Po pół minuty będziesz wiedzieć, czy narzędzie działa z twoimi plikami.

Gdy będziesz gotowy, poznaj Ailoot.