日本語

A full-screen pager for PDFs and images, with familiar less(1) keybindings. View documents directly in your terminal, locally or over SSH.

pdfless requires a terminal that supports iTerm2's inline image protocol. It has been tested with iTerm2 and WezTerm.

• Display PDF, image (PNG/JPEG/GIF...), and plain text files on a terminal.
• Office documents, SVG, and Markdown are also supported with additional dependencies.
• Scroll, zoom, and pan with the keyboard or mouse.
• View paginated documents continuously, with adjacent pages on screen together.
• Search PDF text and follow external and internal PDF links.
• Jump to a section from the table of contents: a PDF's bookmarks, Markdown headings, and Word headings or PowerPoint slide titles (with LibreOffice).
• Switch to text mode to read or copy extracted text.
• Show a clickable and draggable scrollbar.
• Show page thumbnails down the left edge, and click one to go to its page.
• Open multiple files and switch between them.
• Reload the current file automatically when it changes (in follow mode).

You need Python 3.9+, uv, and a compatible terminal. PDF viewing also requires Poppler. Poppler is not needed for plain image files.

Install the prerequisites:

# macOS (Homebrew)
brew install uv poppler

# Ubuntu / Debian
sudo apt install poppler-utils
curl -LsSf https://astral.sh/uv/install.sh | sh

Clone the repository and open a file. uv installs the Python dependencies automatically on the first run.

git clone https://github.com/ktabe/pdfless.git
cd pdfless
./pdfless.py document.pdf

To run it as pdfless, copy the script to a writable directory on your PATH:

cp pdfless.py /usr/local/bin/pdfless
chmod +x /usr/local/bin/pdfless

Alternatively, install the Python dependencies and run without uv:

pip install pillow pypdf markdown weasyprint merm
python3 pdfless.py document.pdf

To check what is installed, run pdfless --doctor. It lists the programs and Python libraries pdfless uses, says what will not work without the missing ones, and exits with status 1 if Poppler is missing. Inside tmux, it also checks the tmux settings.

For other document types, see Additional formats. For use inside tmux, see Caveats.

pdfless document.pdf           # Open a PDF
pdfless image.png              # Open an image
pdfless notes.txt              # Open a text file
pdfless report.pdf chart.png   # Open multiple files
pdfless slides/                # Open the files in a directory
pdfless -p 10 document.pdf     # Start on page 10
pdfless -h slides.pdf          # Fit each page to the terminal height
pdfless -f document.pdf        # Reload when the file changes
pdfless -F document.pdf        # Quit if the document fits on one screen
cat document.pdf | pdfless     # Read from standard input

With multiple files open, use :n / :p (or } / {) to switch files, or O to pick one from a list. A directory stands for the files directly in it, sorted by name (ignoring case, as ls does); hidden files and subdirectories are left out. With no filename, or with - as the filename, pdfless reads standard input.

The following examples show common ways to adjust the view and move through a document. The complete list of keyboard and mouse controls is in Keyboard and mouse controls.

Pages fit the terminal width by default. Press m to fit the current page to the terminal height, or M to return to fitting it to the width.

Press + / - to zoom in or out. Use h / l (or the arrow keys) to pan, and press 0 to reset the zoom and position.

Press / and enter a pattern to search forward, or ? to search backward. Matches are boxed in image mode and highlighted in text mode. Use n / p to move between matches.

Press t to switch to extracted text, then search or copy it using the terminal's normal selection controls. Press T to switch directly to a clean copying view.

Press o or TAB to open the table of contents. Select a heading with j / k or the mouse, then press ENTER or click it to jump to that section. Use [ / ] to go back and forward through positions jumped to from the outline or an internal link.

Click a PDF link to open an external URL in the system browser or follow an internal link. The [ / ] keys return to the previous or next position.

When multiple files are open, press O to show the file chooser. Move with j / k or the mouse wheel, then press ENTER or click a file to open it. Press q to close the chooser. :n / :p and } / { switch to the next or previous file without opening the chooser.

In image mode, press S to show or hide page thumbnails on the left. The current page is framed, and clicking a thumbnail moves to that page. Press s to move focus to the thumbnails; select one with j / k and press ENTER to open it. Press q or s to return to the page while leaving the thumbnails visible. The sidebar requires a terminal at least 60 columns wide.

Press c to toggle continuous mode. This displays the pages continuously, so you can scroll from one page to the next without switching pages.

Image files open directly in image mode. Press t or T to view image information and metadata in text mode.

Press F1 or :h to open the keyboard help. Press q to close it.

Note that -h means fit to height; use --help for command-line help. Follow mode watches only the currently displayed file. Press F to toggle it on or off at any time, or use -f/--follow to enable it at startup. The status line shows follow while the mode is active.

^ denotes Ctrl. Many commands accept the same keys as less(1).

While entering a search pattern with / or ?, use the following keys to edit the input. These bindings apply only while the search prompt is active.

Search is case-insensitive and supports Python regular expressions. Before matching, it normalizes Unicode width and composition (NFKC): 第5回 finds 第５回, データ finds half-width ﾃﾞｰﾀ or decomposed kana, and file finds the fi ligature. Spaces next to Japanese or Chinese text are ignored, so プロジェクトX also finds the プロジェクト X a Word document's PDF often reads as. Elsewhere, any run of spaces matches one space.

The kind of pattern determines how line breaks are handled:

• A pattern without regular-expression syntax is searched as a literal string and may cross line breaks. An invalid regular expression is also treated as literal text.
• A valid regular expression matches within one printed line, as in less. While entering the pattern, press ^T to toggle Multi-line mode and let it match across line breaks as well.

For example:

Matches are boxed in PDF image mode and highlighted in text mode.

Search requires text: it is available for PDFs with extractable text, plain text files, and supported formats rendered to PDF. It is unavailable for plain images and previews without extractable text. While a search is active, n / p move between matches rather than pages.

To copy text from image mode, press T to switch to text mode with borders, line numbers, end-of-line markers, and the scrollbar hidden. You can also press t, then C. If you are already in text mode, use C to toggle these display elements. Select text using the terminal's normal selection controls; press C again to restore the previous display settings.

PNG, JPEG, and other image formats supported by Pillow open directly. Press t or T to view image information in text mode, including the filename, format, pixel dimensions, color mode, file size, DPI, and transparency.

EXIF metadata and embedded text chunks are also shown when present. GPS metadata includes decimal latitude and longitude and a coordinate pair you can paste into Google Maps. Embedded text may include screenshot-tool tags or AI image-generation prompts.

The formats below require additional software. PDF-based rendering also requires Poppler.

• LibreOffice enables OpenDocument, Visio, and WMF support. When installed, it is also preferred for Word, RTF, PowerPoint, and Excel rendering.
• macOS Quick Look and Chrome/Chromium enable iWork previews and provide a fallback for Word, RTF, PowerPoint, and Excel when LibreOffice is absent.
• Chrome/Chromium enables SVG rendering without Quick Look.
• WeasyPrint system libraries enable Markdown rendering. The Python packages markdown and weasyprint are installed with the other Python dependencies. Fenced Mermaid code blocks are rendered to diagrams via merm (also installed with those packages); without merm, they stay as code blocks.

# macOS (Homebrew)
brew install --cask libreoffice
brew install cairo pango gdk-pixbuf libffi

# Ubuntu / Debian
sudo apt install libreoffice
sudo apt install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0

Install Chrome or Chromium separately if you need Quick Look or SVG rendering.

Preview quality and pagination depend on the format and available renderer.