To convert an image to ASCII art in Python, resize the decoded image to a character grid, convert each cell to grayscale, and map its brightness to a character from a density ramp.

This produces visual ASCII art rather than optical character recognition: it represents visible tones with ordinary text characters but does not recognize objects, words, or meaning. The Python example below uses Pillow, prints the result to the terminal, and saves it as a plain-text file.

convert image to ascii art python
Convert Image to ASCII Art in Python: Full Script

What the Python conversion pipeline does

Image-to-ASCII conversion combines image resizing with tone mapping. Each character in the finished grid represents one sampled cell from the resized image. A dense symbol can represent a dark area, while a sparse symbol or space can represent a light area.

  • Decode the source file into pixels and select the frame to convert.
  • Composite transparent pixels over white so they have a defined brightness.
  • Calculate a text-grid height that accounts for the shape of a typical monospace character cell.
  • Resize the image to the planned number of columns and rows.
  • Convert each resized pixel to a brightness value and select a character from the density ramp.
  • Join the character rows with newline separators to create the final text.

Build a Python converter step by step

The following workflow creates a reusable script rather than tying the conversion to a particular image. The snippets use semicolons so several short Python statements fit on one displayed line; you can also place each statement on its own line.

  1. Create a Python environment and install Pillow. Run python -m venv .venv in your project folder. Activate it with .venv\Scripts\activate on Windows or source .venv/bin/activate on macOS and Linux, then install the dependency with python -m pip install Pillow. Using python -m pip helps ensure the package is installed for the same Python interpreter that will run the script.
  2. Create a file named image_to_ascii.py and add the imports and settings: from pathlib import Path; from PIL import Image, ImageOps; RAMP = "@%#*+=-:. "; source_path = "input.jpg"; columns = 100; reverse = False. The ramp deliberately ends with a space, so keep that final character inside the closing quote. The sample uses ten characters because its brightness mapping selects indices from zero through nine.
  3. Decode the image, select its first frame, and place transparency over a white background: source = Image.open(source_path); source.seek(0); rgba = source.convert("RGBA"); source.close(); white = Image.new("RGBA", rgba.size, (255, 255, 255, 255)); rgb = Image.alpha_composite(white, rgba).convert("RGB"); gray = ImageOps.grayscale(rgb). For an animated GIF, the script converts the first frame rather than following its animation.
  4. Calculate the output height and resize the image to the text grid: width, height = gray.size; rows = max(1, int(height / width * columns * 0.5 + 0.5)); small = gray.resize((columns, rows), Image.Resampling.LANCZOS); ramp = RAMP[::-1] if reverse else RAMP; pixels = list(small.getdata()). Here, columns is the number of output characters across, not the number of source pixels. Set it to a positive integer appropriate for the destination terminal or text editor.
  5. Map the grayscale values to characters and assemble the rows: to_char = lambda pixel: ramp[min(9, max(0, int(pixel / 255 * 9 + 0.5)))]; render_row = lambda row_number: "".join(to_char(pixel) for pixel in pixels[row_number * columns:(row_number + 1) * columns]); text = "\n".join(map(render_row, range(rows))). The to_char function maps the darkest grayscale value to the first ramp character and the lightest value to the last. The render_row function collects one row at a time.
  6. Display and save the completed art: print(text); Path("output.txt").write_text(text, encoding="utf-8"). Run the program with python image_to_ascii.py. The terminal receives the preview, while output.txt contains only the generated characters and newline separators.

To convert another picture, replace source_path with its filename or full path. Set reverse to True when the reversed density direction better represents the image.

Keep the character grid proportional

ASCII output is usually displayed in a monospace font, but character cells are commonly taller than they are wide. A practical row calculation is round(source height ÷ source width × output columns × 0.5), with a minimum of one row. The 0.5 factor compensates for that approximate one-to-two character-cell shape.

For example, a 1200 × 600 source at 100 columns produces 600 ÷ 1200 × 100 × 0.5 = 25 rows, giving a grid of 100 columns by 25 rows. This correction preserves the source proportions in the generated text grid rather than treating every character cell as a square.

The result can still look taller or shorter after it reaches an editor, terminal, or web page. Font choice, line height, zoom, and letter spacing all affect the final display. Use a monospace font with tight line spacing, and reduce the column count if the terminal wraps long rows.

Choose and reverse the density ramp

In the sample, the normal ramp moves from @ for dark pixels toward a space for light pixels. Setting reverse = True reverses the entire sequence, causing light regions to receive dense characters and dark regions to receive sparse ones.

  • Keep the ramp at ten symbols when using the supplied brightness formula; changing its length also requires changing the index calculation.
  • Test both directions for images with a bright subject on a dark background or dark lettering on a light background.
  • Increase contrast before resizing when tones appear washed out, but avoid amplifying compression noise in detailed photographs.
  • Use more columns when small facial or architectural features disappear, while checking that the destination can display the longer rows.

Only the resized brightness grid determines each character. The script does not preserve the original colors, even though it converts the image to grayscale before mapping the tones.

Fix common Python conversion problems

  • “No module named PIL”: Install Pillow with python -m pip install Pillow while using the same Python installation or virtual environment that launches the script.
  • “Cannot identify image file”: A matching filename extension does not prove that the file contains valid image data. Confirm that the source is genuinely an image and that the installed Pillow build includes a decoder for its format and codec profile.
  • The result is only one frame: The sample explicitly selects frame zero. To select another animated GIF frame, call source.seek(frame_number) before converting it to RGBA.
  • Transparent areas look black: Composite the RGBA image over white before grayscale conversion, as shown in the script. A fully transparent region then behaves like a light background rather than an opaque black area.
  • Rows wrap in the terminal: Lower the column count or reduce the terminal font size. The generated file can still be valid even when the active terminal is too narrow to show each row on one line.
  • The output differs from a browser converter: Pillow’s grayscale conversion and LANCZOS resampling are not guaranteed to produce the same sampled pixels as browser Canvas processing. The character-mapping principle can match while individual characters still differ.

Run the same conversion in a browser

For a no-setup alternative, Image To Ascii performs the same general luminance-to-text workflow locally in the current browser tab. The supported sequence is straightforward:

  1. Choose one PNG, JPEG, GIF, or WebP file that is within the visible encoded and decoded limits.
  2. Enter a whole output width from 10 through 200 characters and optionally reverse the fixed density ramp.
  3. Generate the complete ASCII result, then copy the visible text or download the local TXT file.

The browser must actually decode the image before conversion. A matching extension or MIME type only passes the initial format screen; malformed content and unsupported codec profiles can still fail during decoding. Animated GIF input is handled as one still frame rather than a changing animation.

Feature Python script Image To Ascii
Input One local path decoded by the installed Pillow build One PNG, JPEG, GIF, or WebP decoded by the browser
Processing location Local Python process Current browser tab
Output width Set by the script; resource use depends on the generated size Strict base-10 whole number from 10 through 200
Density control Editable ten-character ramp in the sample, plus a reverse flag Fixed ten-character ramp with an optional reverse setting
Animation First frame in this sample One still frame
Output Console text and a UTF-8 TXT file Copyable preview and local plain-text download
Source limits Dependent on Pillow and available system resources 15 MiB encoded size, 8,192 pixels per decoded side, and 24 million decoded pixels
Result limit No fixed text cap in the sample 50,000 characters, including every newline separator

Browser limits that determine whether conversion completes

The browser tool’s width field is strict. Widths of 10 and 200 are accepted, while values outside that range fail instead of being clamped. The field also rejects signs, units, whitespace, decimals, leading-zero forms, and scientific notation.

A tall image can exceed the 50,000-character result budget even when its requested width is valid. In that case, the tool reports the limit and produces no partial preview or download; it never silently shortens the completed result. Unsupported or over-limit source images also clear any previous ASCII instead of leaving incomplete output.

All decoding, resizing, pixel reading, luminance calculation, copying, and TXT creation happen in the current browser tab. The image, pixels, generated text, and filename are not uploaded to Lizely. Browser resampling can also vary slightly between rendering engines, particularly for fine patterns or severe reductions.

Know what the text output preserves

ASCII art is a luminance visualization, so the downloadable text is much less complete than the source image. Keep the original file whenever visual fidelity, transparency, animation, metadata, camera information, layers, embedded profiles, or archival details matter.

  • The output contains ordinary characters and newline separators, not the original compressed image.
  • Color, transparency, animation, metadata, camera information, layers, and embedded profiles are not retained.
  • Transparent source pixels are composited over white for luminance calculation.
  • The browser tool uses W3C relative luminance, while the Python sample uses Pillow’s grayscale conversion, so identical source files can produce different characters.
  • A monospace font with tight line height gives the most consistent preview across browsers, editors, and terminals.