Jobs without a permissions block get the repository's default token
scope, and reusable workflow calls pass the caller's grants straight
through. Scopes are now derived from what each workflow actually does
with the token:
- every build workflow declares contents: read; none of them writes
through the GITHUB_TOKEN.
- build-linux-hosts.yml keeps security-events: write for the CodeQL
upload; the other callers had that grant too but never upload
scanning results, so they drop it.
- build-windows-hosts.yml gets actions: read, which the SignPath
action documents needing to read job details and download the
unsigned artifact.
- build-release.yml declares contents: write, matching the grant its
caller already makes for creating the release.
Runs that execute pull request code now hold a token that can do
nothing but read the repository.
Every reusable workflow call used 'secrets: inherit', which hands the
caller's whole secret set to the called workflow, but the only secret
any of them reads is SIGNPATH_API_TOKEN in build-windows-hosts.yml.
Passing that one secret explicitly and dropping inherit everywhere else
means a compromised step in, say, a BSD build VM has no signing token
to steal, and the workflow files now show exactly which secret flows
where.
The secret is declared optional in the reusable workflow so runs
without it (pull requests, forks) behave as before; the signing step
is already guarded to upstream push events.
A version tag like @v1 or a branch like @master is a movable pointer:
whoever controls the action repository can re-point it, and the next
run executes whatever it points at. Several of these actions run in
jobs whose outputs ship to users: build-release.yml creates the GitHub
release with the downloadable binaries, and build-windows-hosts.yml
holds the SignPath signing token, so a re-pointed tag there could ship
a tampered or wrongly signed release. This is exactly how the
tj-actions/changed-files compromise propagated (CVE-2025-30066).
Pinning by full commit SHA makes the reviewed code the code that runs,
the same way docker/setup-qemu-action is already pinned in
build-linux-vms.yml. Refs that pointed at master (cross-platform-actions,
setup-alpine, get-latest-release) are pinned to their latest release
tag. Every pin keeps a version comment, and each SHA was resolved from
the upstream repository and cross-checked against its release tag.
The minimal (core) installation ships the `ubuntustudio-desktop-core`
metapackage instead of `ubuntustudio-desktop`, so the existing check
missed it and the system was reported as Kubuntu.
Fixes#2485
- Add missing ffStrbufDestroy(&options->outputColor) in ffDestroySeparatorOptions
to prevent memory leak when outputColor is set via JSON config
- Replace two exit(1) calls in ffPreparePublicIp with proper error status
propagation, matching the pattern used in the weather module
- Add missing ffStrbufDestroy(&options->outputColor) in ffDestroySeparatorOptions
to prevent memory leak when outputColor is set via JSON config
- Replace two exit(1) calls in ffPreparePublicIp with proper error status
propagation, matching the pattern used in the weather module
The redundant `if (index < strbuf->length)` check inside the static string
branch is always true since `strbuf->length <= index` is already checked
at the top of the function and returns false. Remove this dead code for clarity.
Co-authored-by: tru3 <tru3@tru3.com>
- Add missing ffStrbufDestroy(&options->location) in ffDestroyWeatherOptions
to prevent memory leak when location is set via config
- Replace exit(1) in ffPrepareWeather with setting status to an error string,
allowing the error to be properly propagated through the existing error mechanism
Co-authored-by: tru3 <tru3@tru3.com>
* CI: add loong64 build workflow
Add reusable workflow for building fastfetch on LoongArch 64-bit
architecture using QEMU user-mode emulation + Docker container
(lcr.loongnix.cn/debian:14). Integrate into CI pipeline and
release dependencies.
* CI (loong64): pin docker/setup-qemu-action to full commit SHA
Pin to 06116385d9baf250c9f4dcb4858b16962ea869c3 (v4.1.0) for
immutable action reference as required by Codacy.
ffBase64EncodeRaw unconditionally byte-swapped the input word via
__builtin_bswap32, which only produces the intended big-endian byte
layout on little-endian hosts. On big-endian hosts the word is already
in the correct order, so the swap corrupted the encoded output.
Guard the swap with __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ so the
encoder is correct on both endiannesses.
* add support for proxmox backup server detection
* Update Proxmox identifiers and pretty names
* Simplify Proxmox logo names in p.inc
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* Logo: add chimera2, parabola2_small, postmarketos2, qubes_small
* Logo: add types to chimera2, parabola2_small, postmarketos2, qubes_small, remove "parabola-gnulinux"
* Change logo names to use capital letters
---------
Co-authored-by: v_v <circlepuller@inbox.lv>
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* added small chimera linux logo
* Add logo type for Chimera_small
---------
Co-authored-by: Weed <weedygmd>
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* Create zerene.txt
* Update z.inc
* Fixed z.inc
Changed the problematic line mismatch
* Update z.inc
* Update z.inc
more fixes to z.inc
* Remove duplicate name entry for Zerene logo
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
Update the large logo for OpenWrt based on the official branding.
Add a small logo version.
Keep the old logo as openwrt_old.txt
Signed-off-by: Valeriy Kosikhin <vkosikhin@gmail.com>
* [fix]: markdown-link to wiki
* [fix]: fix color at 1 spot
* [fix]: fix color at 1 spot, again
* Revert "[fix]: markdown-link to wiki"
This reverts commit 72f4d11c90.
"Remove unrelated changes"
* Improved terminal name detection for nix packages
* Improved terminal name detection for nix packages
* Update terminalshell_linux.c
Move ffStrbufStartsWithC(&result->processName, '.') before string comparation, as it's much cheaper.
* Logo: Add openRuyi
* Update ASCII art in openruyi.txt
* Fix casing of 'openRuyi' in builtin.c
---------
Co-authored-by: Z572 <z572@z572.online>
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* Wallpaper (Haiku): Add support
* Refactor wallpaper detection logic and memory handling
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* feat(os): enhance Deepin detection with os-version data
Add a Deepin-specific enhancement in Linux OS detection that reads
`/etc/os-version` for `MinorVersion` and `EditionName`.
When available, it now:
- sets `versionID` to `MinorVersion`
- updates `prettyName` to include version and optional edition
This improves Deepin version accuracy and provides a clearer OS name
than relying solely on generic `os-release` fields.feat(os): enhance Deepin detection with os-version data
Add a Deepin-specific enhancement in Linux OS detection that reads
`/etc/os-version` for `MinorVersion` and `EditionName`.
When available, it now:
- sets `versionID` to `MinorVersion`
- updates `prettyName` to include version and optional edition
This improves Deepin version accuracy and provides a clearer OS name
than relying solely on generic `os-release` fields.
* fix(os): use distro name when formatting Deepin prettyName
Update Deepin enhancement formatting to build `prettyName` from
`result->name` instead of hardcoding "Deepin". This keeps output
consistent with the detected distro name while still appending version
and edition details.fix(os): use distro name when formatting Deepin prettyName
Update Deepin enhancement formatting to build `prettyName` from
`result->name` instead of hardcoding "Deepin". This keeps output
consistent with the detected distro name while still appending version
and edition details.
* fix(os/linux): guard Deepin minor version override
Only apply Deepin’s `minor` value to `versionID` when an edition is
present and `prettyName` does not already include parenthesized details.
This avoids incorrectly overriding parsed version info in enhanced names.fix(os/linux): guard Deepin minor version override
Only apply Deepin’s `minor` value to `versionID` when an edition is
present and `prettyName` does not already include parenthesized details.
This avoids incorrectly overriding parsed version info in enhanced names.
Co-authored-by: Copilot <copilot@github.com>
* Refactor Deepin enhancement detection logic
* Refactor detectDeepinEnhancement function
---------
Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* fix(os): detect Ubuntu Studio before KDE-based flavor checks
Add an explicit Ubuntu Studio detection in `getUbuntuFlavour()` by
checking for `/usr/share/doc/ubuntustudio-desktop` and setting
`name`, `id`, and `idLike` accordingly.
This prevents Ubuntu Studio systems from being misidentified as
Kubuntu when KDE/Plasma-related XDG config paths are present.fix(os): detect Ubuntu Studio before KDE-based flavor checks
Add an explicit Ubuntu Studio detection in `getUbuntuFlavour()` by
checking for `/usr/share/doc/ubuntustudio-desktop` and setting
`name`, `id`, and `idLike` accordingly.
This prevents Ubuntu Studio systems from being misidentified as
Kubuntu when KDE/Plasma-related XDG config paths are present.
* refactor(os): detect Ubuntu Studio via package presence
* Add ASCII logo for KibaOS
* Add KibaOS logo to builtin.c
* Update builtin.c
* Update builtin.c
* Add KibaOS logo to builtin logo configurations
Added KibaOS logo configuration to the logo data structure.
* Fix KibaOS Syntax
* Added support for Redrose.
* Remove 'redrose' OS identification logic
* Remove dollar signs from ASCII art in redrose.txt
* Update logo name from 'redrose' to 'Redrose'
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* Logo (Builtin): adds LimeOS logo
Adds support for LimeOS, a Debian-based distribution.
- Adds ASCII logo (white color scheme)
- Adds OS detection for `ID=limeos`
Homepage: https://limeos.org
* Logo (Builtin): adds LimeOS logo
Adds support for LimeOS, a Debian-based distribution.
Homepage: https://limeos.org
* Logo (Builtin): adds LimeOS logo
* Update builtin.c
```
kde-output-device-v2-client-protocol.h:257:9: error: implicit declaration of function 'wl_proxy_marshal_flags'; did you mean 'wl_proxy_marshal_array'? [-Werror=implicit-function-declaration]
257 | wl_proxy_marshal_flags((struct wl_proxy *) kde_output_device_registry_v2,
| ^~~~~~~~~~~~~~~~~~~~~~
| wl_proxy_marshal_array
```
* Logo (Builtin): adds Emmabuntüs Logo
* Add Detection for Emmabuntüs
* Update ASCII art in emmabuntus.txt
* Remove duplicate name for Emmabuntus logo
* Update emmabuntus.txt
* Update colors for Emmabuntus logo
---------
Co-authored-by: zamhedonia <zamhedonia@gmx.de>
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* fix: colored inside shackle
* Update ASCII art in secureblue.txt
* Fix formatting in secureblue.txt
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* Improves accurancy of detection of drive create time
* Improves performance slightly
* Removes remove drive check, `hideFolders` should be used instead
* Fix Oracle Solaris zpool build
* Add memrchr fallback
* Change to include fron extern
* add new line
* remove ; in zpool.c
* Change wrapper to macro
Also change README.md
* Tweaks
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* Add files via upload
* Update builtin.c
* Update builtin.c
* Update builtin.c
* PrismLinux logo update + small variant
* Update ASCII art in prismlinux.txt
* Revise ASCII art in prismlinux_small.txt
Updated ASCII art in prismlinux_small.txt
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* fix: Codex Linux new logo
reMarkable changed their logo so reflecting that change here too
* Modify ASCII art in codex.txt
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* Add OS2 Warp logo
* Update ASCII art in os2warp.txt
* Refactor OS/2 Warp logo names for consistency
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* Proper detection of lliurex distribution
* fix newline
* Trim version and not versionID as assigned to lliurex-version output
* Update os_linux.c
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* Display: add server vendor string
* Display (X11): fetch server vendor string using XCB/Xlib
* WM: show server vendor string when not empty
* Display (XCB): use proper string helper function
* Display (X11): shorten "The X.Org Foundation" to "Xorg"
Unifies IPv4 and IPv6 default route queries under a shared result structure and per-family functions. Improves clarity and extensibility by centralizing route logic, streamlining detection of preferred interfaces, and updating all consumers to use the new API.
Prepares for more robust multi-protocol network information handling.
* LocalIP: consider preferred source address when retrieving default route
* LocalIP: fix logic error when there is no preferred source address
* LocalIP: use macros rather than manual free/close
* LocalIP(BSD): fix build error
* LocalIP: address Copilot suggestions
Moves module option structs out of global config and removes dynamic allocation, using static buffers and size assertions for safer, simpler management.
Refactors module initialization and destruction to work with isolated option structs, eliminating the need for the previous modules container and related code.
Unifies module option header usage and updates detection logic to leverage statically-sized option buffers, improving encapsulation and maintainability.
Simplifies module function signatures and reduces coupling between modules and config.
Enhances future extensibility and reliability by enforcing max size constraints and removing unnecessary indirections.
This commit addresses an issue where the default route detection on Windows incorrectly identified a disabled adapter as the default route. Previously, when a user disabled the adapter configured as the default route, the system still reported it as active due to stale routing table entries.
Some devices store their CPU name in hw.model, so check that as well
before giving up. Tested on NetBSD 10.1 evbppc/wii, and allows it to
detect the CPU as "750 (Revision 2.0)".
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
The current default behavior of not hiding any GPUs is retained. The new
feature of hiding unknown or unrecognized GPUs can be enabled with
hide-type = "unknown".
* T2/SDE: upstreaming downstream's logo change
T2/SDE port of fastfetch applies two patches, improving the
distribution's logo and adding alternative names. I see no point not
having these upstream.
Downstream's patches are found here:
https://github.com/rxrbln/t2sde/tree/main/package/contrib/fastfetch
The old logo has been renamed to "T2_small".
* Fix ASCII art alignment in t2.txt
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* Logo (Builtin): Add 2 more Alpine logos
* Remove unnecessary $1 in ASCII logo file
* Add type field to Alpine2 logo configuration
---------
Co-authored-by: naix <naix@noreply.codeberg.org>
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
On some PowerPC devices (notably the Nintendo Wii and Nintendo Wii U),
fastfetch detects the CPU incorrectly. It goes down the code path
of 'detectSocName()', and actually matches the model of the device
itself... as the CPU model name. This is obviously incorrect, and
leads to reporting such as 'CPU: wii'. Disable this code path
alltogether on PPC to prevent this, and just let it pull from cpuinfo.
This lets it have correct CPU reporting, such as on the Wii, giving
'CPU: 750CL @ 0.73GHz'.
Wii-Linux-Ngx is no longer the most up to date version of Linux for the Wii.
This change retains the original name for compatibility sake, and because
Neagix's version does indeed still exist. It moves the ASCII art to a more
generic file path, and introduces 2 new aliases for it: Wii-Linux, and WiiLinux.
* add src/logo/ascii/shebang.txt
Support for Shebang Linux
* add Shebang to src/logo/builtin.c
Support for Shebang Linux
* fix Shebang order in builtin.c
* Logo (Builtin): Added Bedrock Linux small ASCII logo
* Logo (Builtin): fixed spacing of small bedrock logo
* Update bedrock_small.txt
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* [chore] Update README.md
move repology badge to install section
customize with `columns` and `minversion` tags
* tweaks
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
Introduces the `-DBUILD_FLASHFETCH='ON'/'OFF'` build option so one can skip the `flashfetch` target (both from executable and install targets, option at `ON` by default to preserve compatibility with the current default behavior).
This is useful when distributing pre-built downstream packages (e.g. for Linux distributions packaging `fastfetch`) as building and shipping the `flashfetch` binary in such pre-built packages serves little to no purpose.
* Add support for detection of Armbian as Ubuntu flavor
Ubuntu can be used to build Armbian, it is one of the official bases for
Armbian. This allows the detection of Armbian in case it is based on
Ubuntu.
* Refactor Armbian detection
* Armbian: set idLike to id before setting id to "armbian"
* Tidy up detectArmbianVersion
A syntax error in the file caused the following output when trying to trigger completions in `zsh` (pressing <TAB>):
```zsh
$ fastfetch File "<stdin>", line 15
command_prefix = f"--logo-color-{i}[{flag["desc"]} ({i})]"
^^^^
SyntaxError: f-string: unmatched '['
```
This fix replaces single quotes with double quotes in the f-strings in lines 37 and 41.
* [macOS] Added support for dual CPUs on Mac computers
Signed-off-by: Koneko <azimovp17@gmail.com>
* Change how number of cores is displayed when the system is dual CPU
* Support for dual CPU on Windows
* Dual CPU detection on Linux basic implementation
---------
Signed-off-by: Koneko <azimovp17@gmail.com>
* Fixed the destination where fastfetch.1 is generated.
* Update CMakeLists.txt
Reappend trailing new line
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* host(macOS): add HwModel support for new Mac (iMac, Mac mini and Macbook Pro 2024)
* Update host_apple.c
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* Add initial support for MidnightBSD
* Cleanup some issues identified through code review.
Add libzfs check as MidnightBSD does have zfs.
* Add MidnightBSD check to the version.c detection
* Remove `OR MidnightBSD` tests
* Clean up
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* putting xeroarch logo in askii
* updating logo
* updating
* updating
* uploading xeroarch ascii logo
* upgrading fetch ascii logo
* fixing a very small issue
* removing unecessary line
* removing trailing lines
* fixing erroneous colors in the logo
---------
Co-authored-by: xeroarch <xeroarch.os@gmail.com>
* run.sh: Improve compatibility with other systems
For example $OSTYPE is empty in OpenBSD and the script fallsback to Linux option, with nproc isn't present it fails to build.
* Update run.sh
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* putting xeroarch logo in askii
* updating logo
* updating
* updating
* uploading xeroarch ascii logo
* upgrading fetch ascii logo
* fixing a very small issue
* removing unecessary line
* removing trailing lines
Both the zsh and fish completions depend on python3.
When the completitions kick in with those shells where no python3 is
found it throws errors.
Check python3 is installed, otherwise return no completitions to avoid
throwing errors
Co-authored-by: Andrew Davis <adavis@adavis.net>
DRM connectors have two properties, "enabled" and "status", standing for
"enabled by userspace" and "a display has been connected". Connector
status cannot be reliably detected sometimes, in this case status will
be set to unknown and it is still okay to enable it. Some drivers are
also able to enable disconnected connectors.
So it is both meaningful to detect connectors in two states,
- An enabled connector, where it must have been operating in some
configuration required by userspace
- A connected connector, where driver is sure a display has been
connected to the port, this is the obvious case.
In the original implementation, only information of connected connectors
are detected and an enabled connector without hotplug detection
capability, like a Composite video connector, will be silently ignored.
Switch to the new strategy to detect these connectors correctly.
References: https://github.com/torvalds/linux/blob/3efc57369a0ce8f76bf0804f7e673982384e4ac9/include/drm/drm_connector.h#L58-L89
Signed-off-by: Yao Zi <ziyao@disroot.org>
* lainos to top of FFlogo K
* Add LliureX art
* Add lliurex detect
* OS (Linux): fix coding style
* Update lliurex.txt
* Update builtin.c
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
* Logo (Builtin): Add Steam Deck Logo
* accidentally removed newline after steam deck oled block
* Update builtin.c
---------
Co-authored-by: Carter Li <CarterLi@users.noreply.github.com>
Be sure to read the [FAQ](https://github.com/fastfetch-cli/fastfetch?tab=readme-ov-file#faq) before submitting a new issue.
<!-- We will try hard to solve the issue. However since platforms and hardwares vary greatly, it can be hard to find the root cause of an issue. Providing the following information may help us greatly. Thanks in advance! -->
# General description of bug:
* What happened:
* What should happen:
* Fastfetch version used: <!-- please use the latest version, if possible -->
* Did it work in an older version: <!-- if yes, which version -->
* Where did you get the binary: <!-- GitHub release / GitHub Actions / installed with a package manager (please tell us which package manager you used!) / built from source yourself -->
* Does this issue still occur in [the latest dev build](https://github.com/fastfetch-cli/fastfetch/actions/)?
# Often helpful information:
Screenshot:
<!-- Paste the screenshot here -->
The content of the configuration file you use (if any):
```
// Paste here
```
Output of `fastfetch -c ci.jsonc --format json`:
<!--
Note that this output will contain you public IP. If it is not relevant for the issue, feel free to remove it before uploading.
-->
```
// Paste here
```
Output of `fastfetch --list-features`:
```
// Paste here
```
## If fastfatch crashed or froze
Paste the stacktrace here. You may get it with:
```shell
# You may need Ctrl+C to stop the process if it freezes
Thanks for taking the time to fill out this bug report! We will try hard to solve the issue.
However since platforms and hardwares vary greatly, it can be hard to find the root cause of an issue.
Providing the following information may help us greatly. Thanks in advance!
- type:checkboxes
attributes:
label:Read the FAQ first
description:Please check if the issue is already covered in the FAQ.
options:
- label:I have checked the FAQ but the issue is not covered
required:true
- type:checkboxes
attributes:
label:Not a known issue
description:Please check if the issue is already known and being worked on.
options:
- label:I have checked the existing issues but the issue is not covered
required:true
- label:My issue is not about crashing on Fedora and KDE 6.6
required:true
- type:markdown
attributes:
value:"### General description of the bug"
- type:textarea
attributes:
label:Description
description:A clear and concise description of what the bug is.
placeholder:I was trying to [...] but [...]
validations:
required:true
- type:input
attributes:
label:Version used
description:Fastfetch version used. Please use the latest version (found in the [releases](https://github.com/fastfetch-cli/fastfetch/releases)) if possible.
placeholder:Result of `fastfetch --version`
validations:
required:true
- type:dropdown
attributes:
label:Bug prevalence
description:How often does the bug occur?
options:
-
- Always
- Sometimes
- Rarely
- Once
- Other
validations:
required:true
- type:dropdown
attributes:
label:Regression
description:Did it work in an older version?
options:
-
- Not sure
- 'Yes'
- 'No'
validations:
required:true
- type:dropdown
attributes:
label:Installation
description:Where did you install fastfetch from?
options:
-
- GitHub Releases
- GitHub Actions (nightly)
- Built from source
- Package manager
validations:
required:true
- type:input
attributes:
label:Package manager
description:Which package manager did you use if applicable?
placeholder:e.g. `apt`, `pacman`, `brew`, `scoop`
- type:markdown
attributes:
value:'### Often helpful information'
- type:textarea
attributes:
label:Screenshots
description:If applicable, add screenshots to help explain your problem.
- type:textarea
attributes:
label:Configuration
description:If applicable, paste your configuration file here.
placeholder:cat ~/.config/fastfetch/config.jsonc
render:jsonc
- type:markdown
attributes:
value:|
Paste the stacktrace here. You may get it with:
```shell
# You may need Ctrl+C to stop the process if it freezes
description:If something is not working as expected (wrong output, missing info, etc)
title:"[BUG] "
labels:["bug","triage"]
body:
- type:markdown
attributes:
value:|
Thanks for taking the time to fill out this bug report! We will try hard to solve the issue.
However since platforms and hardwares vary greatly, it can be hard to find the root cause of an issue.
Providing the following information may help us greatly. Thanks in advance!
- type:checkboxes
attributes:
label:Read the FAQ first
description:Please check if the issue is already covered in the FAQ.
options:
- label:I have checked the FAQ but the issue is not covered
required:true
- type:markdown
attributes:
value:"### General description of the bug"
- type:textarea
attributes:
label:Description
description:A clear and concise description of what the bug is.
placeholder:I was trying to [...] but [...]
validations:
required:true
- type:input
attributes:
label:Version used
description:Fastfetch version used. Please use the latest version (found in the [releases](https://github.com/fastfetch-cli/fastfetch/releases)) if possible.
placeholder:Result of `fastfetch --version`
validations:
required:true
- type:dropdown
attributes:
label:Bug prevalence
description:How often does the bug occur?
options:
-
- Always
- Sometimes
- Rarely
- Once
- Other
validations:
required:true
- type:dropdown
attributes:
label:Regression
description:Did it work in an older version?
options:
-
- Not sure
- 'Yes'
- 'No'
validations:
required:true
- type:dropdown
attributes:
label:Installation
description:Where did you install fastfetch from?
options:
-
- GitHub Releases
- GitHub Actions (nightly)
- Built from source
- Package manager
validations:
required:true
- type:input
attributes:
label:Package manager
description:Which package manager did you use if applicable?
placeholder:e.g. `apt`, `pacman`, `brew`, `scoop`
- type:markdown
attributes:
value:'### Often helpful information'
- type:textarea
attributes:
label:Screenshots
description:If applicable, add screenshots to help explain your problem.
- type:textarea
attributes:
label:Configuration
description:If applicable, paste your configuration file here.
placeholder:cat ~/.config/fastfetch/config.jsonc
render:jsonc
- type:textarea
attributes:
label:System information
description:Output of `fastfetch -c all.jsonc --stat --format json`
placeholder:|
Note that this output will contain you public IP.
If it is not relevant for the issue, feel free to remove it before uploading.
description:If my image logo is not displayed correctly
title:"[BUG] "
labels:["bug","logo","triage"]
body:
- type:markdown
attributes:
value:|
Thanks for taking the time to fill out this bug report! We will try hard to solve the issue.
However since platforms and hardwares vary greatly, it can be hard to find the root cause of an issue.
Providing the following information may help us greatly. Thanks in advance!
- type:checkboxes
attributes:
label:Read the FAQ first
description:Please check if the issue is already covered in the FAQ.
options:
- label:I have checked the FAQ but the issue is not covered
required:true
- type:markdown
attributes:
value:"### General description of the bug"
- type:textarea
attributes:
label:Description
description:A clear and concise description of what the bug is.
placeholder:I was trying to [...] but [...]
validations:
required:true
- type:input
attributes:
label:Version used
description:Fastfetch version used. Please use the latest version (found in the [releases](https://github.com/fastfetch-cli/fastfetch/releases)) if possible.
placeholder:Result of `fastfetch --version`
validations:
required:true
- type:dropdown
attributes:
label:Bug prevalence
description:How often does the bug occur?
options:
-
- Always
- Sometimes
- Rarely
- Once
- Other
validations:
required:true
- type:dropdown
attributes:
label:Regression
description:Did it work in an older version?
options:
-
- Not sure
- 'Yes'
- 'No'
validations:
required:true
- type:dropdown
attributes:
label:Installation
description:Where did you install fastfetch from?
options:
-
- GitHub Releases
- GitHub Actions (nightly)
- Built from source
- Package manager
validations:
required:true
- type:input
attributes:
label:Package manager
description:Which package manager did you use if applicable?
placeholder:e.g. `apt`, `pacman`, `brew`, `scoop`
- type:markdown
attributes:
value:'### Often helpful information'
- type:textarea
attributes:
label:Screenshots
description:If applicable, add screenshots to help explain your problem.
- type:textarea
attributes:
label:Configuration
description:If applicable, paste your configuration file here.
placeholder:cat ~/.config/fastfetch/config.jsonc
render:jsonc
- type:markdown
attributes:
value:|
#### If an image or logo didn't show
Please make sure your terminal supports the image protocol you used.
Note that GNOME Terminal doesn't support any image protocols as of now
Some tips:
1. Try `fastfetch --show-errors` to see if there are any errors.
2. Try `fastfetch --logo-width {WIDTH} --logo-height {HEIGHT}`. Some protocols may require a image size being set.
- type:input
attributes:
label:Image protocol
description:The image protocol you used
validations:
required:true
- type:input
attributes:
label:Terminal
description:The terminal you used
validations:
required:true
- type:textarea
attributes:
label:Image tried
description:Upload the image file, or paste the image URL here
validations:
required:true
- type:textarea
attributes:
label:Error message
description:Error message printed by `fastfetch -s none --show-errors`, if any
Tip: A logo can be displayed by fastfetch without getting into fastfetch's official repo. For highly customized logo for personal use, it's recommended to keep it locally. Please refer to https://github.com/fastfetch-cli/fastfetch/wiki/Migrate-Neofetch-Logo-To-Fastfetch
# OS
```
Paste content of /etc/os-release and /etc/lsb-release here. If none of these files exist, describe a way to identify the distro
```
# Ascii
An ASCII logo should not take up too much space (smaller than 50x20 characters). Please also include the color codes if not available in `os-release`
description:Request a new ASCII logo for your favorite distro
title:"[LOGO] "
labels:["logo request"]
body:
- type:markdown
attributes:
value:|
> [!WARNING]
> **NB:** If your logo request does not meet the basic requirements outlined in this template, the issue may be closed at any time without any further explanation.
**Tip:** You can display a logo in fastfetch without adding it to fastfetch's official repo.
For highly customized, personal logos, we recommend keeping them locally.
You can test your logo locally using:
`fastfetch -l /path/to/logo.txt --logo-color-1 white --logo-color-2 red`
Please refer to the [Migration Guide](https://github.com/fastfetch-cli/fastfetch/wiki/Migrate-Neofetch-Logo-To-Fastfetch) for details on color placeholders (`$1`, `$2`, etc.).
- type:textarea
attributes:
label:OS
description:Paste the contents of `/etc/os-release` (specifically the `ID` and `PRETTY_NAME` fields). If neither file exists, describe how to identify the distro.
placeholder:cat /etc/os-release
validations:
required:true
- type:input
attributes:
label:Public repository URL
description:A public repository is required to verify the request. Please provide a link to the repository where the distro is developed.
placeholder:https://github.com/example/distro
validations:
required:true
- type:input
attributes:
label:Distro Website
description:To help prevent spam and verify the request, a distro website is required, and a downloadable ISO must be available on that site.
placeholder:https://example.com
validations:
required:true
- type:textarea
attributes:
label:ASCII Art
description:|
The ASCII logo should not take up too much space (smaller than 50x20 characters, W x H).
**Important:** Fastfetch uses `$1`, `$2`, `$3` etc. for color placeholders. Do NOT use hardcoded ANSI escape codes (like `\033[38;2...m`) or Neofetch's `${c1}` syntax.
Take <https://github.com/fastfetch-cli/fastfetch/tree/dev/src/logo/ascii> as examples.
placeholder:Paste ASCII art with $1, $2 placeholders here
validations:
required:true
- type:input
attributes:
label:Original Image URL
description:If the ASCII art is based on an image, please provide a link to the original image file.
placeholder:Image URL from the distro website mentioned above
- type:checkboxes
attributes:
label:Checklist
options:
- label:My distro has reached a stable state (out of beta, alpha, RC).
required:true
- label:The ASCII art is smaller than 50x20 characters (W x H).
required:true
- label:The ASCII art uses `$N` color placeholders (or colors are natively available in `os-release`).
required:true
- label:The ASCII art has no unnecessary trailing spaces at the end of lines.
required:true
- label:I promise that I will send a removal request if the distro is discontinued.
body:"Please refer to [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/${{ needs.linux-amd64.outputs.ffversion }}/CHANGELOG.md) for details."
Fastfetch is a [neofetch](https://github.com/dylanaraps/neofetch)-like tool for fetching system information and displaying it prettily. It is written mainly in C, with performance and customizability in mind. Currently, Linux, Android, FreeBSD, macOS, SunOS and Windows 7+ are supported.
Fastfetch is a [neofetch](https://github.com/dylanaraps/neofetch)-like tool for fetching system information and displaying it in a visually appealing way. It is written mainly in C, with a focus on performance and customizability. Currently, it supports Linux, macOS, Windows 8.1+, Android, FreeBSD, OpenBSD, NetBSD, DragonFly, Haiku and SunOS (illumos, Solaris).
> Note: Fastfetch is only actively tested on x86-64 and aarch64 platforms. It may work on other platforms but is not guaranteed to do so.
* Ubuntu: [`ppa:zhangsongcui3371/fastfetch`](https://launchpad.net/~zhangsongcui3371/+archive/ubuntu/fastfetch) (Ubuntu 22.04 or newer; latest version)
* Debian / Ubuntu: `apt install fastfetch` (Debian 13 or newer; Ubuntu 25.04 or newer)
* Debian / Ubuntu: Download `fastfetch-linux-<proper architecture>.deb` from [Github release page](https://github.com/fastfetch-cli/fastfetch/releases/latest) and double-click it (for Ubuntu 20.04 or newer and Debian 11 or newer).
* Arch Linux: `pacman -S fastfetch`
* Fedora: `dnf install fastfetch`
@@ -40,21 +50,18 @@ Some distros packaged an outdated fastfetch version. Older version receive no su
You may need `sudo`, `doas` or `sup` to run these commands.
You may need `sudo`, `doas`, or `sup` to run these commands.
[See also if fastfetch has been packaged for your favorite Linux distro](#Packaging).
If fastfetch is not packaged for your distro or an outdated version is packaged, [linuxbrew](https://brew.sh/) is a good alternative: `brew install fastfetch`
If fastfetch is not packaged for your distribution or an outdated version is packaged, [linuxbrew](https://brew.sh/) is a good alternative: `brew install fastfetch`
* [MacPorts](https://ports.macports.org/port/fastfetch/): `sudo port install fastfetch`
### Windows
@@ -66,72 +73,72 @@ If fastfetch is not packaged for your distro or an outdated version is packaged,
You may also download the program directly from [the GitHub releases page](https://github.com/fastfetch-cli/fastfetch/releases/latest) in the form of an archive file.
See Wiki: https://github.com/fastfetch-cli/fastfetch/wiki/Building
See the Wiki: https://github.com/fastfetch-cli/fastfetch/wiki/Building
## Usage
* Run it with default configuration: `fastfetch`
* Run it with [all supported modules](https://github.com/fastfetch-cli/fastfetch/wiki/Support+Status#available-modules) and find what you interest: `fastfetch -c all.jsonc`
*Find all data that fastfetch detects: `fastfetch -s <module> --format json`
* Run with default configuration: `fastfetch`
* Run with [all supported modules](https://github.com/fastfetch-cli/fastfetch/wiki/Support+Status#available-modules) to find what interests you: `fastfetch -c all.jsonc`
*View all data that fastfetch detects: `fastfetch -s <module1>[:<module2>][:<module3>] --format json`
* Display help messages: `fastfetch --help`
* Generate config file based on command line arguments: `fastfetch --arg1 --arg2 --gen-config`
* Use: `--gen-config-full` to generate a full config file with all optional options
## Customization
Fastfetch uses the JSONC (or JSON with comments) for configuration. [See Wiki for detail](https://github.com/fastfetch-cli/fastfetch/wiki/Configuration). There are some premade config files in [`presets`](presets), including the ones used for the screenshots above. You can load them using `-c <filename>`. Those files can serve as examples of the configuration syntax.
Fastfetch uses JSONC (JSON with comments) for configuration. [See the Wiki for details](https://github.com/fastfetch-cli/fastfetch/wiki/Configuration). There are some premade config files in the [`presets`](presets) directory, including those used for the screenshots above. You can load them using `-c <filename>`. These files can serve as examples of the configuration syntax.
Logos can be heavily customized too; see the [logo documentation](https://github.com/fastfetch-cli/fastfetch/wiki/Logo-options) for more information.
Logos can also be heavily customized; see the [logo documentation](https://github.com/fastfetch-cli/fastfetch/wiki/Logo-options) for more information.
Fastfetch supports a `Command` module that can run arbitrary shell commands. If you copy-paste a config file from an untrusted source, it may contain malicious commands that can harm your system or compromise your privacy. Please always review the config file before using it.
## FAQ
### Q: Neofetch is good enough. Why do I need fastfetch?
1. Fastfetch is actively maintained.
2. Fastfetch is faster. As the name suggests.
3. Fastfetch has a greater number of features, though by default fastfetch only has a few modules enabled; use `fastfetch -c all` to find what you want.
2. Fastfetch is faster, as the name suggests.
3. Fastfetch has a greater number of features, though by default it only has a few modules enabled; use `fastfetch -c all` to discover what you want.
4. Fastfetch is more configurable. You can find more information in the Wiki: <https://github.com/fastfetch-cli/fastfetch/wiki/Configuration>.
5. Fastfetch is more polished. For example, neofetch prints `555MiB` in `Memory` module and `23G` in `Disk` module, whereas fastfetch prints `555.00 MiB` and `22.97 GiB` respectively.
5. Fastfetch is more polished. For example, neofetch prints `555MiB` in the Memory module and `23G` in the Disk module, whereas fastfetch prints `555.00 MiB` and `22.97 GiB` respectively.
6. Fastfetch is more accurate. For example, [neofetch never actually supports the Wayland protocol](https://github.com/dylanaraps/neofetch/pull/2395).
### Q: Fastfetch shows my local IP address. It leaks my privacy!
### Q: Fastfetch shows my local IP address. Does it leak my privacy?
A local IP (10.x.x.x, 172.x.x.x, 192.168.x.x) has nothing to do with privacy. It only makes sense if you are on the same network, for example, if you connect to the same Wi-Fi network.
A local IP address (10.x.x.x, 172.x.x.x, 192.168.x.x) has nothing to do with privacy. It only has meaning if you are on the same network, for example, if you connect to the same Wi-Fi network.
Actually the `Local IP` module is the most useful module for me personally. I (@CarterLi) have several VMs installed to test fastfetch and often need to SSH into them. I have fastfetch running on shell startup and I never need to type `ip addr` manually.
Actually, the `Local IP` module is the most useful module for me personally. I (@CarterLi) have several VMs installed to test fastfetch and often need to SSH into them. With fastfetch running on shell startup, I never need to type `ip addr` manually.
If you really don't like it, you can disable the `Local IP` module in `config.jsonc`.
### Q: Where is the config file? I can't find it.
`Fastfetch` does not generate config file automatically. You can use `fastfetch --gen-config` to generate one. The config file will be saved in `~/.config/fastfetch/config.jsonc` by default. See [Wiki for detail](https://github.com/fastfetch-cli/fastfetch/wiki/Configuration).
Fastfetch does not generate a config file automatically. You can use `fastfetch --gen-config` to generate one. The config file will be saved in `~/.config/fastfetch/config.jsonc` by default. See the [Wiki for details](https://github.com/fastfetch-cli/fastfetch/wiki/Configuration).
### Q: The configuration is so complex. Where is the documentation?
Fastfetch uses JSON (with comments) for configuration. I suggest you use an IDE with JSON schema support (like VSCode) to edit it.
Fastfetch uses JSON (with comments) for configuration. I suggest using an IDE with JSON schema support (like VSCode) to edit it.
Alternatively, you can refer to the presets in [`presets` directory](https://github.com/fastfetch-cli/fastfetch/tree/dev/presets).
Alternatively, you can refer to the presets in the [`presets` directory](https://github.com/fastfetch-cli/fastfetch/tree/dev/presets).
The **correct** way to edit the configuration:
@@ -141,32 +148,32 @@ This is an example that [changes size prefix from MiB / GiB to MB / GB](https://
### Q: I WANT THE DOCUMENTATION!
[Here is the documentation](https://github.com/fastfetch-cli/fastfetch/wiki/Json-Schema). It is generated from [JSON schema](https://github.com/fastfetch-cli/fastfetch/blob/dev/doc/json_schema.json) but you won't like it.
[Here is the documentation](https://github.com/fastfetch-cli/fastfetch/wiki/Json-Schema). It is generated from the [JSON schema](https://github.com/fastfetch-cli/fastfetch/blob/dev/doc/json_schema.json), but you might not find it very user-friendly.
### Q: How can I customize the module output?
Fastfetch uses `format` to generate output. For example, to make the `GPU` module show only the GPU name (leaving other information undisplayed), you can use
Fastfetch uses `format` to generate output. For example, to make the `GPU` module show only the GPU name (leaving other information undisplayed), you can use:
```jsonc
{
"modules":[
{
"type":"gpu",
"format":"{2}"// See `fastfetch -h gpu-format` for detail
"format":"{name}"// See `fastfetch -h gpu-format` for details
}
]
}
```
. . which is equivalent to `fastfetch -s gpu --gpu-format '{2}'`
...which is equivalent to `fastfetch -s gpu --gpu-format '{name}'`
See `fastfetch -h format` for information on basic usage. For modulespecific formattion, see `fastfetch -h <module>-format`
See `fastfetch -h format` for information on basic usage. For module-specific formatting, see `fastfetch -h <module>-format`
### Q: I have my own ascii-art / image file. How can I show it with fastfetch?
### Q: I have my own ASCII art / image file. How can I show it with fastfetch?
Try `fastfetch -l /path/to/logo`. See [logo documentation](https://github.com/fastfetch-cli/fastfetch/wiki/Logo-options) for detail.
Try `fastfetch -l /path/to/logo`. See the [logo documentation](https://github.com/fastfetch-cli/fastfetch/wiki/Logo-options) for details.
If you just want to display distro name in [FIGlet text](https://github.com/pwaller/pyfiglet):
If you just want to display the distro name in [FIGlet text](https://github.com/pwaller/pyfiglet):
### Q: Fastfetch runs in white and black on shell startup. Why?
### Q: My image logo behaves strangely. How can I fix it?
This issue usually happens when using fastfetch with `p10k`. There are known incompatibility between fastfetch and p10k instant prompt.
The p10k doc clearly states that you should NOT print anything to stdout after `p10k-instant-prompt` is initialized. You should either put `fastfetch` before initialization of `p10k-instant-prompt` (recommended)
See the troubleshooting section: <https://github.com/fastfetch-cli/fastfetch/wiki/Logo-options#troubleshooting>
You can always use `fastfetch --pipe false` to force fastfetch running in colorful mode.
### Q: Fastfetch runs in black and white on shell startup. Why?
### Q: Why do fastfetch and neofetch show different memory usage result?
This issue usually occurs when using fastfetch with `p10k`. There are known incompatibilities between fastfetch and p10k instant prompt.
The p10k documentation clearly states that you should NOT print anything to stdout after `p10k-instant-prompt` is initialized. You should put `fastfetch` before the initialization of `p10k-instant-prompt` (recommended).
You can always use `fastfetch --pipe false` to force fastfetch to run in colorful mode.
### Q: Why do fastfetch and neofetch show different memory usage results?
See [#1096](https://github.com/fastfetch-cli/fastfetch/issues/1096).
### Q: Fastfetch shows fewer dpkg packages than neofetch. Is it a bug?
1. Neofetch incorrectly counts `rc` packages for apt (packages that have been removed but still have configuration files remaining). See bug: https://github.com/dylanaraps/neofetch/issues/2278
2. Neofetch incorrectly counts `gpg-pubkey` as packages for rpm. You may check the results of `dnf list --installed | wc -l` and `rpm -qa | wc -l` to see the difference.
### Q: I use Debian / Ubuntu / Debian-derived distro. My GPU is detected as `XXXX Device XXXX (VGA compatible)`. Is this a bug?
Try upgrading `pci.ids`: Download <https://pci-ids.ucw.cz/v2.2/pci.ids> and overwrite the file `/usr/share/hwdata/pci.ids`. For AMD GPUs, you should also upgrade `amdgpu.ids`: Download <https://gitlab.freedesktop.org/mesa/drm/-/raw/main/data/amdgpu.ids> and overwrite the file `/usr/share/libdrm/amdgpu.ids`
Alternatively, you may try using `fastfetch --gpu-driver-specific`, which will make fastfetch attempt to ask the driver for the GPU name if supported.
### Q: I get the error `Authorization required, but no authorization protocol specified` when running fastfetch as root
"source":"C:/path/to/image.png",// Do NOT use `~` as fastfetch is a native Windows program and doesn't apply cygwin path conversion
"width":<image-width-in-chars>,// Optional
"height":<image-height-in-chars>// Optional
}
}
```
* If you installed fastfetch via scoop or downloaded the binary directly from the GitHub Releases page:
1. Convert your image manually to sixel format using [any online image conversion service](https://www.google.com/search?q=convert+image+to+sixel)
2. In `config.jsonc`:
```jsonc
{
"logo":{
"type":"raw",// DO NOT USE "auto"
"source":"C:/path/to/image.sixel",
"width":<image-width-in-chars>,// Required
"height":<image-height-in-chars>// Required
}
}
```
### Q: I want feature A / B / C. Will fastfetch support it?
Fastfetch is a system information tool. We only accept hardware or systemlevel software feature requests. For most personal uses, I recommend using `Command` module to detect it yourself, which can be used to grab output from a custom shell script:
Fastfetch is a system information tool. We only accept hardware or system-level software feature requests. For most personal uses, I recommend using the `Command` module to implement custom functionality, which can be used to grab output from a custom shell script:
```jsonc
// This module shows the default editor
@@ -203,16 +312,28 @@ Fastfetch is a system information tool. We only accept hardware or system level
}
```
Otherwise, open a feature request in [GitHub Issues](https://github.com/fastfetch-cli/fastfetch/issues).
Otherwise, please open a feature request in [GitHub Issues](https://github.com/fastfetch-cli/fastfetch/issues).
### Q: I have questions. Where can I get help?
* For usage questions, please start a discussion in [GitHub Discussions](https://github.com/fastfetch-cli/fastfetch/discussions).
* For possible bugs, please open an issue in [GitHub Issues](https://github.com/fastfetch-cli/fastfetch/issues). Be sure to fill the bug-report template carefully for developers to investigate.
* For possible bugs, please open an issue in [GitHub Issues](https://github.com/fastfetch-cli/fastfetch/issues). Be sure to fill out the bugreport template carefully to help developers investigate.
## Donate
If you find Fastfetch useful, please consider donating.
* Current maintainer: [@CarterLi](https://paypal.me/zhangsongcui)
* Original author: [@LinusDierheimer](https://github.com/sponsors/LinusDierheimer)
## Code signing
* Free code signing provided by [SignPath.io](https://about.signpath.io/), certificate by [SignPath Foundation](https://signpath.org/)
* This program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it
fastfetch \- a neofetch\-like tool for fetching system information and
displaying them in a pretty way
fastfetch \- a fast and customizable system information tool similar to neofetch
.SH SYNOPSIS
@@ -11,15 +10,12 @@ displaying them in a pretty way
.SH DESCRIPTION
Fastfetch is a neofetch\-like tool for fetching system information and
displaying them in a pretty way. It is written mainly in C, with performance
and customizability in mind.
Currently, Linux, Android, FreeBSD, MacOS and Windows 7+ are supported.
Fastfetch is a tool for displaying system information in a visually appealing way. Written primarily in C, it focuses on performance and customizability while providing functionality similar to neofetch.
It supports Linux, Android, *BSD, macOS, Haiku, and Windows 7 or newer.
.SH "EXIT STATUS"
On successful execution, fastfetch returns zero. If any error happened,
the exit code will be non\-zero.
Fastfetch returns zero on successful execution. Any errors result in a non-zero exit code.
.SH OPTIONS
@@ -27,115 +23,200 @@ the exit code will be non\-zero.
.TP
.B \-h, \-\-help \fI[command]
Show help output, displaying all available options or help for given command
Display help information for all available options or for a specific command
.TP
.B \-v, \-\-version
Show version of fastfetch
Display the version of fastfetch
.TP
.B \-\-version\-raw
Display the raw version string (major.minor.patch)
.TP
.B \-\-list\-config\-paths
List search paths of config files
List search paths for configuration files
.TP
.B \-\-list\-data\-paths
List search paths of presets and logos
List search paths for presets and logos
.TP
.B \-\-list\-logos
List available logos, they can be loaded with \fI\-\-logo
List available logos that can be loaded with \fI\-\-logo
.TP
.B \-\-list\-modules
List available modules
List all available modules
.TP
.B \-\-list\-presets
List available presets, they can be loaded with \fI\-\-config
List available presets that can be loaded with \fI\-\-config
.TP
.B \-\-list\-features
List the supported features fastfetch was compiled with
List the features that fastfetch was compiled with (mainly for development)
.TP
.B \-\-print\-logos
Print available logos
Display all available logos
.TP
.B \-\-print\-structure
Print the default structure
Display the default structure
.TP
.B \-\-format \fI<type>
Set the output format. Besides the
.I default
format, only
.I json
is supported currently.
.SS "Display Options"
.TP
.B \-l, \-\-logo \fI<logo>
Set the logo to display
.TP
.B \-s, \-\-structure \fI<structure>
Set the structure of the fetch. For details about the structure,
see the CONFIGURATION section.
Set the output format. Available options are:
.RS
.IP \(bu 2
\fIdefault\fR: Default human-readable format
.IP \(bu 2
\fIjson\fR: JSON format for machine processing
.RE
.SS "Config Options"
.TP
.B \-c, \-\-config \fI<config>
Use the specified config file or preset. If
.I none
is specified, disable further config loading. For details about
config files, see the CONFIGURATION section
Use the specified config file or preset. Specify \fInone\fR to disable further config loading. See the CONFIGURATION section for details on config files.
.TP
.B \-\-gen\-config \fI[file]
Generate a config file with options specified on the command line.
If \fIfile\fR is specified, the configuration will be written to the
file, otherwise it will be written to stdout.
.B \-\-gen\-config \fI[path]
Generate a config file with options specified on the command line. If \fIpath\fR is not specified, it defaults to \fB~/.config/fastfetch/config.jsonc\fR. If \fIpath\fR is "\-", the configuration will be written to stdout.
.TP
.B \-\-gen\-config\-force \fI[file]
Same as \fB\-\-gen\-config\fR, but overwrites existing config
.B \-\-gen\-config\-force \fI[path]
Same as \fB\-\-gen\-config\fR, but overwrites any existing file at the destination path.
.TP
.SS "Logo Options"
.TP
To list all options, use \fB\-\-help\fR. It will also print all available module options.
.B \-l, \-\-logo \fI<logo>
Set the logo to display. Can be the name of a built-in logo or a path to an image file. Use \fInone\fR to disable the logo.
.TP
.B \-\-logo\-type \fI<type>
Set the type of the logo specified with \fI\-\-logo\fR. Available types include \fIauto\fR, \fIbuiltin\fR, \fIfile\fR, \fIsixel\fR, \fIkitty\fR, and others. See \fB\-\-help logo\-type\fR for details.
.TP
.B \-\-logo\-width \fI<width>
Set the width of the logo in characters (for image logos)
.TP
.B \-\-logo\-height \fI<height>
Set the height of the logo in characters (for image logos)
.TP
.B \-\-logo\-color\-[1\-9] \fI<color>
Override specific colors in the logo
.SS "Display Options"
.TP
.B \-s, \-\-structure \fI<structure>
Set the structure of the fetch (a colon-separated list of module names)
.TP
.B \-\-color \fI<color>
Set the color of keys and title. See \fB\-\-help color\fR for available colors.
.TP
.B \-\-color\-keys \fI<color>
Set the color of keys only
.TP
.B \-\-color\-title \fI<color>
Set the color of the title only
.TP
.B \-\-separator \fI<string>
Set the separator between key and value (default: ": ")
.TP
.B \-\-key\-width \fI<num>
Align the width of keys to \fI<num>\fR characters
.TP
.B \-\-show\-errors
Display errors when they occur (default: false)
.TP
.B \-\-pipe
Disable colors (automatically detected based on whether stdout is a terminal)
To list all available options including module-specific options, use \fB\-\-help\fR.
.SH CONFIGURATION
.SS "Fetch Structure"
The structure of a fetch describes the modules that should be included in
the output. It consists of a string of modules, separated by a colon (:).
The structure defines which modules to display and in what order. It consists of module names separated by colons (:).
For example: \fBtitle:separator:os:kernel:uptime\fR
To list all available modules, use \fB\-\-list\-modules\fR
.SS "Config Files"
Fastfetch uses JSONC based format for configuration. Fastfetch doesn't generate
config file automatically; it should be generated manually by \fB\-\-gen\-config\fR.
The config file will be saved in \fB~/.config/fastfetch/config.jsonc\fR by default.
Fastfetch uses JSONC for configuration files. JSONC is JSON with support for comments (// and /* */). Configuration files must have the .jsonc extension.
A JSONC config file is a JSON file that also supports comments with (// and /* */).
Those files must have the extension '.jsonc'.
You can generate a default config file using \fB\-\-gen\-config\fR. By default, the config file is saved at \fB~/.config/fastfetch/config.jsonc\fR.
The specified configuration/preset files are searched in the following order:
The configuration/preset files are searched in the following locations (in order):
1. relative to the current working directory
.RS
.IP 1. 4
Relative to the current working directory
.IP 2. 4
Relative to ~/.local/share/fastfetch/presets/
.IP 3. 4
Relative to /usr/share/fastfetch/presets/
.RE
2. relative to ~/.local/share/fastfetch/presets/
For detailed information on logo options, module configuration, and formatting, visit:
"desc":"Show this help message or help for a specific command",
"arg":{
"type":"command",
"optional":true
}
},
{
"short":"v",
"long":"version",
"desc":"Show the full Fastfetch version"
},
{
"long":"version-raw",
"desc":"Show the raw version string (major.minor.patch)"
},
{
"long":"list-config-paths",
"desc":"List search paths for config files"
},
{
"long":"list-data-paths",
"desc":"List search paths for presets and logos"
},
{
"long":"list-logos",
"desc":"List available logos"
},
{
"long":"list-modules",
"desc":"List available modules"
},
{
"long":"list-presets",
"desc":"List available presets",
"remark":"Presets can be loaded with \"--config <preset-name>\""
},
{
"long":"list-features",
"desc":"List the supported features that fastfetch was compiled with",
"remark":"Mainly for development"
},
{
"long":"print-logos",
"desc":"Show available logos"
},
{
"long":"print-structure",
"desc":"Show the default structure"
},
{
"long":"format",
"desc":"Set the output format",
"arg":{
"type":"enum",
"enum":{
"default":"Default format",
"json":"JSON format"
},
"default":"default"
}
},
{
"long":"json",
"short":"j",
"arg":{
"type":"bool",
"default":false,
"optional":true
},
"desc":"Enable or disable JSON output",
"remark":"Shortcut for `--format json`"
},
{
"long":"dynamic-interval",
"desc":"Keep Fastfetch running and refresh the output every <num> milliseconds",
"remark":"Set to 0 (default) to disable this behavior; does not work with --json",
"arg":{
"type":"num",
"default":0
}
},
{
"long":"watch",
"short":"w",
"desc":"Alias of dynamic-interval, but the value is in seconds instead of milliseconds. If no value is provided, it defaults to 1 second",
"arg":{
"type":"num",
"optional":true,
"default":1
}
}
],
"Config":[
{
"short":"c",
"long":"config",
"desc":"Specify the config file or preset to load",
"remark":"The file is searched in the order shown by \"fastfetch --list-config-paths\". Use \"-\" to read config from stdin, or \"none\" to disable further config loading. See also https://github.com/fastfetch-cli/fastfetch/wiki/Configuration for details",
"arg":{
"type":"config"
}
},
{
"long":"gen-config",
"desc":"Interactively generate a config file at the specified path",
"remark":"Opens an interactive configuration UI when run in a terminal. Falls back to non-interactive generation when env-var `$NO_COLOR` is set or stdin/stdout is not a TTY. Defaults to \"~/.config/fastfetch/config.jsonc\". Prints the generated config if <path> is \"-\"",
"arg":{
"type":"path",
"optional":true
}
}
],
"General":[
{
"long":"thread",
"desc":"Use separate threads for HTTP requests",
"arg":{
"type":"bool",
"optional":true,
"default":true
}
},
{
"long":"wmi-timeout",
"desc":"Set the timeout (ms) for WMI queries",
"remark":"Windows only",
"arg":{
"type":"num",
"default":5000
}
},
{
"long":"processing-timeout",
"desc":"Set the timeout (ms) when waiting for child processes",
"arg":{
"type":"num",
"default":5000
}
},
{
"long":"ds-force-drm",
"desc":"Specify whether display detection should use DRM only",
"remark":[
"Use this option if you encounter problems with other detection methods.",
"Linux only"
],
"arg":{
"type":"enum",
"optional":true,
"default":"false",
"enum":{
"true":"Try `libdrm` first, then `sysfs` if libdrm fails",
"sysfs-only":"Use `/sys/class/drm` only",
"false":"Try `wayland`, then `x11`, then `drm`"
}
}
},
{
"long":"detect-version",
"desc":"Specify whether to detect and display versions for terminal, shell, editor, and others",
"remark":"Mainly for benchmarking",
"arg":{
"type":"bool",
"optional":true,
"default":true
}
}
],
"Logo":[
{
"short":"l",
"long":"logo",
"desc":"Set the logo source. Use \"none\" to disable logo output",
"remark":"Use either a built-in logo name or a path to an image file. See also https://github.com/fastfetch-cli/fastfetch/wiki/Logo-options",
"arg":{
"type":"logo"
}
},
{
"long":"logo-type",
"desc":"Set the type of logo specified by \"--logo\"",
"remark":"See also https://github.com/fastfetch-cli/fastfetch/wiki/Logo-options",
"arg":{
"type":"enum",
"enum":{
"auto":"If a value is provided, try built-in first, then file. Otherwise auto-detect the logo",
"builtin":"Built-in ASCII art",
"small":"Built-in ASCII art, small version",
"file":"Text file, printed with color code replacement",
"file-raw":"Text file, printed as is",
"data":"Text data, printed with color code replacement",
"data-raw":"Text data, printed as is",
"sixel":"Image file, rendered as sixel",
"kitty":"Image file, rendered using the Kitty graphics protocol",
"kitty-direct":"Image file, tells the terminal emulator to read image data from the specified file",
"kitty-icat":"Image file, displayed using `kitten icat`. Requires the `kitten` binary",
"iterm":"Image file, rendered using the iTerm graphics protocol",
"chafa":"Image file, printed as ASCII art using libchafa",
"raw":"Image file, printed as raw binary string",
"none":"Disable logo printing"
}
}
},
{
"long":"logo-width",
"desc":"Set the width of the logo (in characters) if it is an image",
"remark":"Required for iTerm image protocol",
"arg":{
"type":"num"
}
},
{
"long":"logo-height",
"desc":"Set the height of the logo (in characters) if it is an image",
"remark":"Required for iTerm image protocol",
"arg":{
"type":"num"
}
},
{
"long":"logo-preserve-aspect-ratio",
"desc":"Specify whether the logo should fill the specified width and height as much as possible without stretching",
"remark":"Supported by iTerm image protocol only",
"arg":{
"type":"bool",
"optional":true,
"default":false
}
},
{
"long":"logo-color-[1-9]",
"desc":"Override a color in the logo",
"remark":"See `-h color` for the list of available colors",
"arg":{
"type":"color"
},
"pseudo":true
},
{
"long":"logo-padding",
"desc":"Set the padding on the left and right sides of the logo",
"arg":{
"type":"num"
}
},
{
"long":"logo-padding-left",
"desc":"Set the padding on the left side of the logo",
"arg":{
"type":"num"
}
},
{
"long":"logo-padding-right",
"desc":"Set the padding on the right side of the logo",
"arg":{
"type":"num"
}
},
{
"long":"logo-padding-top",
"desc":"Set the padding at the top of the logo",
"arg":{
"type":"num"
}
},
{
"long":"logo-print-remaining",
"desc":"Specify whether to print remaining logo lines when the logo is taller than the module list",
"arg":{
"type":"bool",
"optional":true,
"default":true
}
},
{
"long":"logo-position",
"desc":"Set the display position of the logo",
"arg":{
"type":"enum",
"enum":{
"left":"Left",
"top":"Top",
"right":"Right"
}
}
},
{
"long":"logo-recache",
"desc":"If true, regenerate the image logo cache",
"arg":{
"type":"bool",
"optional":true,
"default":false
}
},
{
"long":"file",
"desc":"Short for --logo-type file --logo <path>",
"remark":"See \"--help logo-type\" for more info",
"arg":{
"type":"path"
}
},
{
"long":"file-raw",
"desc":"Short for --logo-type file-raw --logo <path>",
"remark":"See \"--help logo-type\" for more info",
"arg":{
"type":"path"
}
},
{
"long":"data",
"desc":"Short for --logo-type data --logo <data>",
"remark":"See \"--help logo-type\" for more info",
"arg":{
"type":"data"
}
},
{
"long":"data-raw",
"desc":"Short for --logo-type data-raw --logo <data>",
"remark":"See \"--help logo-type\" for more info",
"arg":{
"type":"data"
}
},
{
"long":"raw",
"desc":"Short for --logo-type raw --logo <path>",
"remark":"See \"--help logo-type\" for more info",
"arg":{
"type":"path"
}
},
{
"long":"sixel",
"desc":"Short for --logo-type sixel --logo <path>",
"remark":"See \"--help logo-type\" for more info",
"arg":{
"type":"path"
}
},
{
"long":"kitty",
"desc":"Short for --logo-type kitty --logo <path>",
"remark":"See \"--help logo-type\" for more info",
"arg":{
"type":"path"
}
},
{
"long":"kitty-direct",
"desc":"Short for --logo-type kitty-direct --logo <path>",
"remark":"See \"--help logo-type\" for more info",
"arg":{
"type":"path"
}
},
{
"long":"kitty-icat",
"desc":"Short for --logo-type kitty-icat --logo <path>",
"remark":"See \"--help logo-type\" for more info",
"arg":{
"type":"path"
}
},
{
"long":"iterm",
"desc":"Short for --logo-type iterm --logo <path>",
"remark":"See \"--help logo-type\" for more info",
"arg":{
"type":"path"
}
},
{
"long":"chafa",
"desc":"Short for --logo-type chafa --logo <path>",
"remark":"See \"--help logo-type\" for more info",
"arg":{
"type":"path"
}
},
{
"long":"chafa-fg-only",
"desc":"Produce character-cell output using foreground colors only",
"remark":"See the Chafa documentation for details",
"arg":{
"type":"bool",
"optional":true,
"default":false
}
},
{
"long":"chafa-symbols",
"desc":"Specify character symbols to employ in final output",
"remark":"See the Chafa documentation for details",
"arg":{
"type":"str"
}
},
{
"long":"chafa-canvas-mode",
"desc":"Determine how colors are used in the output",
"remark":"This value maps to the integer value of enum ChafaCanvasMode. See the Chafa documentation for details",
"arg":{
"type":"enum",
"enum":{
"TRUECOLOR":"Truecolor",
"INDEXED_256":"256 colors",
"INDEXED_240":"256 colors, but avoid using the lower 16 whose values vary between terminal environments",
"INDEXED_16":"16 colors using the aixterm ANSI extension",
"FGBG_BGFG":"Default foreground and background colors, plus inversion",
"FGBG":"Default foreground and background colors. No ANSI codes will be used",
"INDEXED_8":"8 colors, compatible with original ANSI X3.64",
"INDEXED_16_8":"16 FG colors (8 of which enabled with bold/bright) and 8 BG colors"
}
}
},
{
"long":"chafa-color-space",
"desc":"Set the color space used for quantization",
"remark":"This value maps to the integer value of enum ChafaColorSpace. See the Chafa documentation for details",
"arg":{
"type":"enum",
"enum":{
"RGB":"RGB color space. Fast but imprecise",
"DIN99D":"DIN99d color space. Slower, but good perceptual color precision"
}
}
},
{
"long":"chafa-dither-mode",
"desc":"Set the output dithering mode (no effect with 24-bit color)",
"remark":"This value maps to the integer value of enum ChafaDitherMode. See the Chafa documentation for details",
"arg":{
"type":"enum",
"enum":{
"NONE":"No dithering",
"ORDERED":"Ordered dithering (Bayer or similar)",
"DIFFUSION":"Error diffusion dithering (Floyd-Steinberg or similar)"
}
}
}
],
"Display":[
{
"short":"s",
"long":"structure",
"desc":"Set the structure of the fetch",
"remark":"Must be a colon-separated list of module keys. Use \"fastfetch --list-modules\" to see available options",
"arg":{
"type":"structure",
"default":"\"fastfetch --print-structure\""
}
},
{
"long":"structure-disabled",
"desc":"Disable specific modules in the structure",
"remark":"Must be a colon-separated list of keys",
"arg":{
"type":"structure"
}
},
{
"long":"stat",
"desc":"Show execution time (ms) for individual modules",
"arg":{
"type":"bool",
"optional":true,
"default":false
}
},
{
"long":"pipe",
"desc":"Disable colors",
"remark":"Auto-detected based on isatty(1) by default",
"arg":{
"type":"bool",
"optional":true,
"default":false
}
},
{
"long":"color",
"desc":"Set the color of both keys and title",
"remark":[
"Shortcut for \"--color-keys <color>\" and \"--color-title <color>\"",
"For color syntax, see <https://github.com/fastfetch-cli/fastfetch/wiki/Color-Format-Specification>"
],
"arg":{
"type":"color"
}
},
{
"long":"color-keys",
"desc":"Set the color of the keys",
"remark":"Doesn't affect Title, Separator, and Colors modules. See `-h color` for the list of available colors",
"arg":{
"type":"color"
}
},
{
"long":"color-title",
"desc":"Set the color of the title",
"remark":"See `-h color` for the list of available colors",
"arg":{
"type":"color"
}
},
{
"long":"color-output",
"desc":"Set the color of module output",
"remark":"See `-h color` for the list of available colors",
"arg":{
"type":"color"
}
},
{
"long":"color-separator",
"desc":"Set the color of the key-value separator",
"remark":"See `-h color` for the list of available colors",
"arg":{
"type":"color"
}
},
{
"long":"duration-abbreviation",
"desc":"Specify whether to abbreviate duration values",
"remark":"If true, output is shown as \"1h 2m\" instead of \"1 hour, 2 mins\"",
"arg":{
"type":"bool",
"optional":true,
"default":false
}
},
{
"long":"duration-space-before-unit",
"desc":"Specify whether to put a space before the unit in duration values",
"arg":{
"type":"enum",
"enum":{
"default":"Use the default behavior of the module",
"always":"Always put a space before the unit",
"never":"Never put a space before the unit"
}
}
},
{
"long":"key-width",
"desc":"Align the width of keys to <num> characters",
"arg":{
"type":"num"
}
},
{
"long":"key-padding-left",
"desc":"Set the left padding of keys to <num> characters",
"arg":{
"type":"num"
}
},
{
"long":"key-type",
"desc":"Specify whether to show an icon before string keys",
"arg":{
"type":"enum",
"enum":{
"none":"Disable keys",
"string":"Show string",
"icon":"Show icon (requires a recent Nerd Font)",
"both":"Show both icon and string (alias of `both-1`)",
"both-0":"Show both icon and string with no spaces between them",
"both-1":"Show both icon and string with a space between them",
"both-2":"Show both icon and string with 2 spaces between them",
"both-3":"Show both icon and string with 3 spaces between them",
"both-4":"Show both icon and string with 4 spaces between them"
},
"default":"string"
}
},
{
"long":"bright-color",
"desc":"Specify whether keys, title, and ASCII logo should be printed in bright color",
"arg":{
"type":"bool",
"optional":true,
"default":true
}
},
{
"long":"separator",
"desc":"Set the separator between key and value",
"arg":{
"type":"str",
"default":": "
}
},
{
"long":"show-errors",
"desc":"Print errors when they occur",
"arg":{
"type":"bool",
"optional":true,
"default":false
}
},
{
"long":"disable-linewrap",
"desc":"Specify whether to disable line wrap during execution",
"arg":{
"type":"bool",
"optional":true,
"default":true
}
},
{
"long":"hide-cursor",
"desc":"Specify whether to hide the cursor during execution",
"arg":{
"type":"bool",
"optional":true,
"default":false
}
},
{
"long":"percent-type",
"desc":"Set the percentage output style",
"remark":[
"1 for percentage number",
"2 for multi-color bar",
"3 for both",
"6 for bar only",
"9 for colored number",
"10 for monochrome bar"
],
"arg":{
"type":"num",
"default":9
}
},
{
"long":"percent-ndigits",
"desc":"Set the number of decimal places to use when formatting percentages",
"arg":{
"type":"num",
"default":0
}
},
{
"long":"percent-color-green",
"desc":"Set color used for the green state of percentage bars and numbers",
"remark":"See `-h color` for the list of available colors",
"arg":{
"type":"color",
"default":"green"
}
},
{
"long":"percent-color-yellow",
"desc":"Set color used for the yellow state of percentage bars and numbers",
"remark":"See `-h color` for the list of available colors",
"arg":{
"type":"color",
"default":"light_yellow"
}
},
{
"long":"percent-color-red",
"desc":"Set color used for the red state of percentage bars and numbers",
"remark":"See `-h color` for the list of available colors",
"arg":{
"type":"color",
"default":"light_red"
}
},
{
"long":"percent-space-before-unit",
"desc":"Specify whether to put a space before the percentage symbol",
"arg":{
"type":"enum",
"enum":{
"default":"Use the default behavior of the module",
"always":"Always put a space before the unit",
"never":"Never put a space before the unit"
}
}
},
{
"long":"percent-width",
"desc":"Specify the width of the percentage number, in characters",
"remark":"This option affects only percentage numbers, not bars",
"arg":{
"type":"num",
"default":0
}
},
{
"long":"bar-char-elapsed",
"desc":"Set the character used for the elapsed part of percentage bars",
"arg":{
"type":"str",
"default":"\u25a0"
}
},
{
"long":"bar-char-total",
"desc":"Set the character used for the total part of percentage bars",
"arg":{
"type":"str",
"default":"-"
}
},
{
"long":"bar-border-left",
"desc":"Set the string to use at the left border of percentage bars",
"arg":{
"type":"string",
"default":"[ "
}
},
{
"long":"bar-border-right",
"desc":"Set the string to use at the right border of percentage bars",
"arg":{
"type":"string",
"default":" ]"
}
},
{
"long":"bar-border-left-elapsed",
"desc":"If both bar-border-left-elapsed and bar-border-right-elapsed are set, the border is used as part of the bar content",
"arg":{
"type":"string",
"default":""
}
},
{
"long":"bar-border-right-elapsed",
"desc":"If both bar-border-left-elapsed and bar-border-right-elapsed are set, the border is used as part of the bar content",
"arg":{
"type":"string",
"default":""
}
},
{
"long":"bar-color-elapsed",
"desc":"Set the color used for the elapsed part of percentage bars",
"remark":"By default, this is auto-selected by percent-color-{green,yellow,red}",
"arg":{
"type":"color",
"default":"<auto>"
}
},
{
"long":"bar-color-total",
"desc":"Set the color used for the total part of percentage bars",
"arg":{
"type":"color",
"default":"light_white"
}
},
{
"long":"bar-color-border",
"desc":"Set the color used for percentage bar borders",
"arg":{
"type":"color",
"default":"light_white"
}
},
{
"long":"bar-width",
"desc":"Set the width of percentage bars in characters",
"arg":{
"type":"num",
"default":10
}
},
{
"long":"no-buffer",
"desc":"Specify whether stdout buffering should be disabled",
"arg":{
"type":"bool",
"optional":true,
"default":false
}
},
{
"long":"size-ndigits",
"desc":"Set the number of decimal places to use when formatting sizes",
"arg":{
"type":"num"
}
},
{
"long":"size-binary-prefix",
"desc":"Set the binary prefix to use when formatting sizes",
nameSection=r"fastfetch \- A fast and feature-rich system information tool similar to neofetch"
# text displayed in the "DESCRIPTION" section
descriptionSection=r"""
Fastfetch is a tool for displaying system information in a visually appealing way. Written primarily in C, it focuses on performance and customizability while providing functionality similar to neofetch.
It supports Linux, Android, FreeBSD, macOS, and Windows 7 or newer.
"""
# text displayed at the beginning of the "OPTIONS" section
optionSection=r"""
Options are parsed in a case-insensitive manner. For example, \fB--logo-type\fR and \fB--LOGO-TYPE\fR are treated identically.
Arguments in square brackets are optional. Optional boolean arguments default to 'true' when specified without a value.
For more detailed information about a specific option, use:
\fBfastfetch -h <option_name_without_dashes>\fR
Any combination of options can be made permanent by generating a configuration file:
\fBfastfetch <options> --gen-config\fR
"""
# text displayed in the "CONFIGURATION"
configurationSection=f"""
.SS Fetch Structure
The structure defines which modules to display and in what order. It consists of module names separated by colons (:).
For example: {startBold}title:separator:os:kernel:uptime{endBold}
To list all available modules, use {startBold}--list-modules{endBold}
.SS Config Files
Fastfetch uses JSONC (JSON with Comments) for configuration files. These files must have the .jsonc extension.
You can generate a default config file using {startBold}--gen-config{endBold}. By default, the config file is saved at {startBold}~/.config/fastfetch/config.jsonc{endBold}.
The configuration/preset files are searched in the following locations (in order):
{startBold}1.{endBold} Relative to the current working directory
{startBold}2.{endBold} Relative to ~/.local/share/fastfetch/presets/
{startBold}3.{endBold} Relative to /usr/share/fastfetch/presets/
For detailed information on logo options, module configuration, and formatting, visit:
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
//
/// \file
/// \mainpage
/// AGS Library Overview
/// --------------------
/// This document provides an overview of the AGS (AMD GPU Services) library. The AGS library provides software developers with the ability to query
/// AMD GPU software and hardware state information that is not normally available through standard operating systems or graphic APIs.
///
/// The latest version of the API is publicly hosted here: https://github.com/GPUOpen-LibrariesAndSDKs/AGS_SDK/.
/// It is also worth checking http://gpuopen.com/gaming-product/amd-gpu-services-ags-library/ for any updates and articles on AGS.
/// \internal
/// Online documentation is publicly hosted here: http://gpuopen-librariesandsdks.github.io/ags/
/// \endinternal
///
/// ---------------------------------------
/// What's new in AGS 6.2 since version 6.1
/// ---------------------------------------
/// AGS 6.2 includes the following updates:
/// * Shader clock intrinsics
/// * Minor improvements and fixes
///
/// ---------------------------------------
/// What's new in AGS 6.1 since version 6.0
/// ---------------------------------------
/// AGS 6.1 includes the following updates:
/// * RDNA3 detection
///
/// ---------------------------------------
/// What's new in AGS 6.0 since version 5.4.2
/// ---------------------------------------
/// AGS 6.0 includes the following updates:
/// * DX12 ray tracing hit token for RDNA2 hardware.
/// * Shader intrinsic that exposes ReadLaneAt in DX12.
/// * Shader intrinsics that expose explicit float conversions in DX12.
/// * Refactored and revised API to minimize user error.
/// * Added agsGetVersionNumber.
/// * Detection for external GPUs.
/// * Detection of RDNA2 architecture.
/// * Grouped the more established intrinsics together into per year support.
/// * Function pointer typedefs for the API
///
/// ---------------------------------------
/// What's new in AGS 5.4.2 since version 5.4.1
/// ---------------------------------------
/// AGS 5.4.2 includes the following updates:
/// * sharedMemoryInBytes has been reinstated.
/// * Clock speed returned for APUs.
///
/// ---------------------------------------
/// What's new in AGS 5.4.1 since version 5.4.0
/// ---------------------------------------
/// AGS 5.4.1 includes the following updates:
/// * AsicFamily_Count to help with code maintenance.
/// * Visual Studio 2019 support.
/// * x86 support
/// * BaseInstance and BaseVertex intrinsics along with corresponding caps bits.
/// * GetWaveSize intrinsic along with corresponding caps bits.
///
/// ---------------------------------------
/// What's new in AGS 5.4 since version 5.3
/// ---------------------------------------
/// AGS 5.4 includes the following updates:
/// * A more detailed description of the GPU architecture, now including RDNA GPUs.
/// * Radeon 7 core and memory speeds returned.
/// * Draw index and Atomic U64 intrinsics for both DX11 and DX12.
///
/// ---------------------------------------
/// What's new in AGS 5.3 since version 5.2
/// ---------------------------------------
/// AGS 5.3 includes the following updates:
/// * DX11 deferred context support for Multi Draw Indirect and UAV Overlap extensions.
/// * A Radeon Software Version helper to determine whether the installed driver meets your game's minimum driver version requirements.
/// * Freesync HDR Gamma 2.2 mode which uses a 1010102 swapchain and can be considered as an alternative to using the 64 bit swapchain required for Freesync HDR scRGB.
///
/// Using the AGS library
/// ---------------------
/// It is recommended to take a look at the source code for the samples that come with the AGS SDK:
/// * AGSSample
/// * CrossfireSample
/// * EyefinitySample
/// The AGSSample application is the simplest of the three examples and demonstrates the code required to initialize AGS and use it to query the GPU and Eyefinity state.
/// The CrossfireSample application demonstrates the use of the new API to transfer resources on GPUs in Crossfire mode. Lastly, the EyefinitySample application provides a more
/// extensive example of Eyefinity setup than the basic example provided in AGSSample.
/// There are other samples on Github that demonstrate the DirectX shader extensions, such as the Barycentrics11 and Barycentrics12 samples.
///
/// To add AGS support to an existing project, follow these steps:
/// * Link your project against the correct import library. Choose from either the 32 bit or 64 bit version.
/// * Copy the AGS dll into the same directory as your game executable.
/// * Include the amd_ags.h header file from your source code.
/// * Include the AGS hlsl files if you are using the shader intrinsics.
/// * Declare a pointer to an AGSContext and make this available for all subsequent calls to AGS.
/// * On game initialization, call \ref agsInitialize passing in the address of the context. On success, this function will return a valid context pointer.
///
/// Don't forget to cleanup AGS by calling \ref agsDeInitialize when the app exits, after the device has been destroyed.
#ifndef AMD_AGS_H
#define AMD_AGS_H
#define AMD_AGS_VERSION_MAJOR 6 ///< AGS major version
#define AMD_AGS_VERSION_MINOR 2 ///< AGS minor version
#define AMD_AGS_VERSION_PATCH 0 ///< AGS patch version
#define AGS_MAKE_VERSION( major, minor, patch ) ( ( major << 22 ) | ( minor << 12 ) | patch ) ///< Macro to create the app and engine versions for the fields in \ref AGSDX12ExtensionParams and \ref AGSDX11ExtensionParams and the Radeon Software Version
#define AGS_UNSPECIFIED_VERSION 0xFFFFAD00 ///< Use this to specify no version
#define AGS_CURRENT_VERSION AGS_MAKE_VERSION( AMD_AGS_VERSION_MAJOR, AMD_AGS_VERSION_MINOR, AMD_AGS_VERSION_PATCH ) ///< Macro to return the current AGS version as defined by the AGS header file
/// @}
/// \defgroup enums General enumerations
/// @{
/// The return codes
typedefenumAGSReturnCode
{
AGS_SUCCESS,///< Successful function call
AGS_FAILURE,///< Failed to complete call for some unspecified reason
AGS_INVALID_ARGS,///< Invalid arguments into the function
AGS_OUT_OF_MEMORY,///< Out of memory when allocating space internally
AGS_MISSING_D3D_DLL,///< Returned when a D3D dll fails to load
AGS_LEGACY_DRIVER,///< Returned if a feature is not present in the installed driver
AGS_NO_AMD_DRIVER_INSTALLED,///< Returned if the AMD GPU driver does not appear to be installed
AGS_EXTENSION_NOT_SUPPORTED,///< Returned if the driver does not support the requested driver extension
AGS_ADL_FAILURE,///< Failure in ADL (the AMD Display Library)
AGS_DX_FAILURE,///< Failure from DirectX runtime
AGS_D3DDEVICE_NOT_CREATED///< Failure due to not creating the D3D device successfully via AGS.
}AGSReturnCode;
/// @}
typedefstructAGSContextAGSContext;///< All function calls in AGS require a pointer to a context. This is generated via \ref agsInitialize
/// The rectangle struct used by AGS.
typedefstructAGSRect
{
intoffsetX;///< Offset on X axis
intoffsetY;///< Offset on Y axis
intwidth;///< Width of rectangle
intheight;///< Height of rectangle
}AGSRect;
/// The display info struct used to describe a display enumerated by AGS
typedefstructAGSDisplayInfo
{
charname[256];///< The name of the display
chardisplayDeviceName[32];///< The display device name, i.e. DISPLAY_DEVICE::DeviceName
unsignedintisPrimaryDisplay:1;///< Whether this display is marked as the primary display
unsignedintHDR10:1;///< HDR10 is supported on this display
unsignedintdolbyVision:1;///< Dolby Vision is supported on this display
unsignedintfreesync:1;///< Freesync is supported on this display
unsignedintfreesyncHDR:1;///< Freesync HDR is supported on this display
unsignedinteyefinityInGroup:1;///< The display is part of the Eyefinity group
unsignedinteyefinityPreferredDisplay:1;///< The display is the preferred display in the Eyefinity group for displaying the UI
unsignedinteyefinityInPortraitMode:1;///< The display is in the Eyefinity group but in portrait mode
unsignedintreservedPadding:24;///< Reserved for future use
intmaxResolutionX;///< The maximum supported resolution of the unrotated display
intmaxResolutionY;///< The maximum supported resolution of the unrotated display
floatmaxRefreshRate;///< The maximum supported refresh rate of the display
AGSRectcurrentResolution;///< The current resolution and position in the desktop, ignoring Eyefinity bezel compensation
AGSRectvisibleResolution;///< The visible resolution and position. When Eyefinity bezel compensation is enabled this will
///< be the sub region in the Eyefinity single large surface (SLS)
floatcurrentRefreshRate;///< The current refresh rate
inteyefinityGridCoordX;///< The X coordinate in the Eyefinity grid. -1 if not in an Eyefinity group
inteyefinityGridCoordY;///< The Y coordinate in the Eyefinity grid. -1 if not in an Eyefinity group
doublechromaticityRedX;///< Red display primary X coord
doublechromaticityRedY;///< Red display primary Y coord
doublechromaticityGreenX;///< Green display primary X coord
doublechromaticityGreenY;///< Green display primary Y coord
doublechromaticityBlueX;///< Blue display primary X coord
doublechromaticityBlueY;///< Blue display primary Y coord
doublechromaticityWhitePointX;///< White point X coord
doublechromaticityWhitePointY;///< White point Y coord
doublescreenDiffuseReflectance;///< Percentage expressed between 0 - 1
doublescreenSpecularReflectance;///< Percentage expressed between 0 - 1
doubleminLuminance;///< The minimum luminance of the display in nits
doublemaxLuminance;///< The maximum luminance of the display in nits
doubleavgLuminance;///< The average luminance of the display in nits
intlogicalDisplayIndex;///< The internally used index of this display
intadlAdapterIndex;///< The internally used ADL adapter index
intreserved;///< reserved field
}AGSDisplayInfo;
/// The ASIC family
typedefenumAsicFamily
{
AsicFamily_Unknown,///< Unknown architecture, potentially from another IHV. Check \ref AGSDeviceInfo::vendorId
AsicFamily_Vega,///< AMD Vega architecture, including Raven Ridge (ie AMD Ryzen CPU + AMD Vega GPU).
AsicFamily_RDNA,///< AMD RDNA architecture
AsicFamily_RDNA2,///< AMD RDNA2 architecture
AsicFamily_RDNA3,///< AMD RDNA3 architecture
AsicFamily_Count///< Number of enumerated ASIC families
}AsicFamily;
/// The device info struct used to describe a physical GPU enumerated by AGS
typedefstructAGSDeviceInfo
{
constchar*adapterString;///< The adapter name string
AsicFamilyasicFamily;///< Set to Unknown if not AMD hardware
unsignedintisAPU:1;///< Whether this device is an APU
unsignedintisPrimaryDevice:1;///< Whether this device is marked as the primary device
unsignedintisExternal:1;///< Whether this device is a detachable, external device
unsignedintreservedPadding:29;///< Reserved for future use
intvendorId;///< The vendor id
intdeviceId;///< The device id
intrevisionId;///< The revision id
intnumCUs;///< Number of compute units
intnumWGPs;///< Number of RDNA Work Group Processors. Only valid if ASIC is RDNA onwards.
intnumROPs;///< Number of ROPs
intcoreClock;///< Core clock speed at 100% power in MHz
intmemoryClock;///< Memory clock speed at 100% power in MHz
intmemoryBandwidth;///< Memory bandwidth in MB/s
floatteraFlops;///< Teraflops of GPU. Zero if not GCN onwards. Calculated from iCoreClock * iNumCUs * 64 Pixels/clk * 2 instructions/MAD
unsignedlonglonglocalMemoryInBytes;///< The size of local memory in bytes. 0 for non AMD hardware.
unsignedlonglongsharedMemoryInBytes;///< The size of system memory available to the GPU in bytes. It is important to factor this into your VRAM budget for APUs
///< as the reported local memory will only be a small fraction of the total memory available to the GPU.
intnumDisplays;///< The number of active displays found to be attached to this adapter.
AGSDisplayInfo*displays;///< List of displays allocated by AGS to be numDisplays in length.
inteyefinityEnabled;///< Indicates if Eyefinity is active
inteyefinityGridWidth;///< Contains width of the multi-monitor grid that makes up the Eyefinity Single Large Surface.
inteyefinityGridHeight;///< Contains height of the multi-monitor grid that makes up the Eyefinity Single Large Surface.
inteyefinityResolutionX;///< Contains width in pixels of the multi-monitor Single Large Surface.
inteyefinityResolutionY;///< Contains height in pixels of the multi-monitor Single Large Surface.
inteyefinityBezelCompensated;///< Indicates if bezel compensation is used for the current SLS display area. 1 if enabled, and 0 if disabled.
intadlAdapterIndex;///< Internally used index into the ADL list of adapters
intreserved;///< reserved field
}AGSDeviceInfo;
/// \defgroup general General API functions
/// API for initialization, cleanup, HDR display modes and Crossfire GPU count
/// @{
typedefvoid*(__stdcall*AGS_ALLOC_CALLBACK)(size_tallocationSize);///< AGS user defined allocation prototype
typedefvoid(__stdcall*AGS_FREE_CALLBACK)(void*allocationPtr);///< AGS user defined free prototype
/// The configuration options that can be passed in to \ref agsInitialize
typedefstructAGSConfiguration
{
AGS_ALLOC_CALLBACKallocCallback;///< Optional memory allocation callback. If not supplied, malloc() is used
AGS_FREE_CALLBACKfreeCallback;///< Optional memory freeing callback. If not supplied, free() is used
}AGSConfiguration;
/// The top level GPU information returned from \ref agsInitialize
typedefstructAGSGPUInfo
{
constchar*driverVersion;///< The AMD driver package version
constchar*radeonSoftwareVersion;///< The Radeon Software Version
intnumDevices;///< Number of GPUs in the system
AGSDeviceInfo*devices;///< List of GPUs in the system
}AGSGPUInfo;
/// The struct to specify the display settings to the driver.
/// The result returned from \ref agsCheckDriverVersion
typedefenumAGSDriverVersionResult
{
AGS_SOFTWAREVERSIONCHECK_OK,///< The reported Radeon Software Version is newer or the same as the required version
AGS_SOFTWAREVERSIONCHECK_OLDER,///< The reported Radeon Software Version is older than the required version
AGS_SOFTWAREVERSIONCHECK_UNDEFINED///< The check could not determine as result. This could be because it is a private or custom driver or just invalid arguments.
}AGSDriverVersionResult;
///
/// Helper function to check the installed software version against the required software version.
///
/// \param [in] radeonSoftwareVersionReported The Radeon Software Version returned from \ref AGSGPUInfo::radeonSoftwareVersion.
/// \param [in] radeonSoftwareVersionRequired The Radeon Software Version to check against. This is specificed using \ref AGS_MAKE_VERSION.
/// \return The version number made using AGS_MAKE_VERSION( AMD_AGS_VERSION_MAJOR, AMD_AGS_VERSION_MINOR, AMD_AGS_VERSION_PATCH ).
///
AMD_AGS_APIintagsGetVersionNumber();
///
/// Function used to initialize the AGS library.
/// agsVersion must be specified as AGS_CURRENT_VERSION or the call will return \ref AGS_INVALID_ARGS.
/// Must be called prior to any of the subsequent AGS API calls.
/// Must be called prior to ID3D11Device or ID3D12Device creation.
/// \note The caller of this function should handle the possibility of the call failing in the cases below. One option is to do a vendor id check and only call \ref agsInitialize if there is an AMD GPU present.
/// \note This function will fail with \ref AGS_NO_AMD_DRIVER_INSTALLED if there is no AMD driver found on the system.
/// \note This function will fail with \ref AGS_LEGACY_DRIVER in Catalyst versions before 12.20.
///
/// \param [in] agsVersion The API version specified using the \ref AGS_CURRENT_VERSION macro. If this does not match the version in the binary this initialization call will fail.
/// \param [in] config Optional pointer to a AGSConfiguration struct to override the default library configuration.
/// \param [out] context Address of a pointer to a context. This function allocates a context on the heap which is then required for all subsequent API calls.
/// \param [out] gpuInfo Optional pointer to a AGSGPUInfo struct which will get filled in for all the GPUs in the system.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Carter Li