Four ways to add images to a GitHub README, plus badges

Choose an image location based on ownership and lifetime

A README image is a documentation dependency. Before choosing a URL, decide who owns the file, whether it must change with the code, how long it should remain available, and where the README will be rendered. A versioned architecture diagram has different requirements from a temporary pull request screenshot or a badge generated from live project data.

For example, keep installation screenshots beside the README when each release documents a different interface. A community logo shared across many repositories may belong in centrally managed public storage instead. Avoid choosing a location solely because it is convenient during editing. Moving images later can break old tags, package pages, forks, and links to historical documentation.

Keep release-specific media in the repository

For a tracked asset, place the file in a predictable directory such as docs/images/ and reference it with Markdown like ![Settings screen](docs/images/settings.png). Relative paths make the README and image move together across branches and forks. Resolve the path from the Markdown file's location, not from the repository root, because a README inside a subdirectory has a different base path.

Treat path spelling as code. Case differences may work on one developer's filesystem but fail elsewhere. Renaming a directory, squashing an image, or deleting an apparently unused file can also break older documents. Review image changes with the text that depends on them, and use descriptive filenames rather than opaque names copied from a screenshot utility.

Pin documentation images to a stable revision when the page describes a released interface or behavior. A branch-relative path is convenient while editing, but the same README can show different artwork after the branch changes. Release notes, security advisories, and versioned setup instructions benefit from immutable references because readers can then see the image that belonged to that exact version rather than the newest replacement.

Treat attachments and remote images as external dependencies

Dragging an image into a GitHub editor can produce a hosted attachment URL. That is fast and avoids adding binary data to the repository, but the resulting asset is not represented by a normal file in Git history. Record why the URL exists, keep the original somewhere controlled, and verify that repository transfers or documentation migrations will not leave the team without a manageable source.

A remote URL can reduce repository size and let one asset update across multiple documents. It can also fail because of an expired signed URL, changed access policy, deleted object, DNS problem, or hotlink restriction. Use an HTTPS location intended for durable public access, confirm that redistribution is permitted, and avoid embedding private endpoints. A request to an external image host may disclose reader network or browser information, so privacy-sensitive projects should minimize unnecessary third-party resources.

Use Markdown for meaning and HTML only for needed layout control

Standard Markdown is the portable default: ![alternative text](path-or-url). It expresses the image's purpose and works across more repository browsers, package registries, documentation generators, and local preview tools. Keep optional hover titles secondary because keyboard and touch users may never receive them, and because a title does not replace alternative text or a visible explanation.

An HTML img element can set dimensions when a screenshot otherwise dominates the page. GitHub sanitizes unsupported HTML, attributes, and styles, so elaborate positioning may disappear or behave differently from a local preview. Prefer a simple element with src, alt, width, and height. Base64 data URLs make Markdown large, difficult to review, and poorly portable; they also prevent normal file caching and should not be the routine answer to asset management.

Prepare images for the size at which people read them

Do not commit a full-resolution desktop capture when the README displays it in a narrow content column. Resize close to the useful reading width, while retaining enough pixel density for sharp text on high-density screens. Compression should remove waste without turning interface labels into artifacts. Compare the optimized result at its rendered size rather than judging only the file-size number.

Choose the format from the content. JPEG suits photographic images that do not need transparency. PNG remains useful for crisp interface captures, limited-color diagrams, and transparency, although it can become large. WebP can work for mixed imagery when every intended renderer is tested. SVG is effective for diagrams and logos created as vectors, but only trusted SVG should be published. Keep an editable source for diagrams even when the README uses an exported raster version.

Write alternative text for the image's role

Alternative text should convey what a reader needs from the image in this context. For a successful test screenshot, describe the relevant success state rather than listing every visible control. For a diagram, summarize the relationship it illustrates and explain complex details in nearby prose. Do not repeat a caption word for word or use a filename such as screen-final-2.png as the description.

A linked image needs text that communicates the link's destination or action, not merely its appearance. Decorative separators and repeated brand marks should have empty alternative text when the renderer permits it, while status badges should receive concise labels such as Build: passing. Essential commands, configuration, or error messages must also appear as selectable text because images cannot provide a reliable copy, search, translation, or zoom experience.

Make artwork survive themes and missing resources

Transparent logos and diagrams often assume a white canvas. On a dark theme, black strokes can disappear; on a light theme, white labels can vanish. Test both themes and add an intentional background or border when one asset can serve both. If the renderer supports theme-specific picture sources, keep the light and dark versions semantically equivalent and give the overall image one useful alternative description.

Design the surrounding paragraph so the README remains understandable while an image is loading or unavailable. Never put the only installation step, security warning, or compatibility requirement inside a screenshot. Avoid meaning conveyed only by color, and check diagrams at increased zoom. These practices support accessibility while also making documentation more resilient in text-only tools, cached package pages, and restricted networks.

Use badges as summaries, not as the source of truth

A badge is a remotely generated image that summarizes changing data such as a build result, package version, or coverage state. Its accuracy depends on the upstream service, query parameters, branch selection, authentication, caching, and refresh behavior. Link the badge to a page where readers can inspect the underlying result, and label it so the meaning is clear without decoding color.

Keep the badge row selective. A long sequence of service calls slows rendering, creates visual noise, and increases the number of parties contacted when someone opens the README. Never use a badge as the only notice of a security issue or supported version. If a provider fails, the project description and normal contributor workflow should still make sense.

Review images as part of documentation testing

Preview the README in GitHub's renderer after committing to a branch. Open every image, verify relative paths from the actual README location, switch color themes, and inspect narrow and zoomed layouts. When the README is published to a package registry or documentation site, test that surface too because relative URL rules and supported HTML can differ.

Add lightweight operational checks for important assets. A link checker can detect missing remote images, while repository review can catch oversized binaries and untracked source files. Revisit screenshots when the interface changes, and remove obsolete assets only after searching all branches of maintained documentation. The goal is not merely a rendered image today, but an understandable document throughout the project's supported lifetime.

Frequently asked questions