SwapDog
SwapDog is a swap watchdog that monitors RAM usage and enables or disables swap devices automatically based on user-defined thresholds. It is designed to prevent excessive swapping, which can lead to performance degradation and SSD wear, while still allowing the system to function without crashing when RAM is exhausted.
Rationale
SwapDog helps you avoid unnecessary swap usage when RAM is available, but will enable swap if memory pressure gets high—and disable it again when pressure drops. This approach is more radical than simply tuning swappiness:
- Swap memory is always slower than RAM; HDDs are especially slow.
- SSDs wear out with read and write cycles, while RAM does not.
- Disabling swap when not needed reduces SSD wear and improves performance.
These reasons are enough for me to want to limit the usage of swap in a more dynamic way than swappiness does.
Installation
Any installation method assumes that you have access to the swapdog.py, swapdog.json, requirements.txt and swapdog.service files in the current directory.
git clone https://github.com/FLAK-ZOSO/SwapDog
cd SwapDog
You may want to proceed with the configuration before installing, but you can also do it later.
Automated
You can use the provided install.sh script to automate the installation process. Just run the following command:
chmod +x install.sh
./install.sh
Manual
Take this as a documentation of the steps that the install.sh script performs, so you can do it manually if you prefer:
- Install dependencies with
sudo pip3 install -r requirements.txt - Copy the swapdog.py file to
/usr/local/sbin/ - Make it executable with
sudo chmod 744 /usr/local/sbin/swapdog.py - Copy the swapdog.json file to
/etc/ - Copy the swapdog.service file to
/etc/systemd/system/ - Enable the service with
sudo systemctl enable swapdog - Start the service with
sudo systemctl start swapdog - Check the status of the service with
sudo systemctl status swapdog
sudo pip3 install -r requirements.txt --break-system-packages
sudo cp swapdog.py /usr/local/sbin/
sudo chmod 744 /usr/local/sbin/swapdog.py
sudo cp swapdog.json /etc/
sudo cp swapdog.service /etc/systemd/system/
sudo systemctl enable swapdog
sudo systemctl start swapdog
sudo systemctl status swapdog
Configuration
In order to configure the behavior of SwapDog, you need to edit the swapdog.json file located in /etc/. The file follows a simple JSON structure that allows you to set thresholds and the swap devices to be used.
Fields
thresholds: An array of objects, each representing a threshold for enabling a swap device.percentage: The percentage of RAM usage that triggers the swap device to be enabled.swap: The path to the swap device (e.g.,/dev/sda1or/swapfile).
period: The time in seconds between checks of the RAM usage. Default is1.0seconds if not specified.disable_swaps: A boolean flag that indicates whether to disable swaps when RAM usage is below the threshold. Default isfalse.hysteresis: A float value that defines the hysteresis for disabling swaps. This is the percentage below the threshold at which swaps will be disabled. Default is10.0if not specified.
How to configure
- Enable all swaps in order to make them easily detectable.
sudo swapon --all
- List the currently enabled swap devices.
sudo swapon --show
sudo cat /proc/swaps
What follows is an example output. You are looking for the NAME column to identify the swap devices.
NAME TYPE SIZE USED PRIO
/dev/dm-1 partition 7.4G 0B -2
/swapfile file 2.0G 0B -3
- Edit the
swapdog.jsonfile to set the desired thresholds and swap devices. For example, if you want to enable a swap device when RAM usage exceeds 95%, you can set it like this:
{
"thresholds": [
{
"percentage": 95.0,
"swap": "/dev/dm-1"
},
{
"percentage": 90.0,
"swap": "/swapfile"
}
],
"period": 1.0,
"disable_swaps": true,
"hysteresis": 15.0
}
Uninstallation
To uninstall SwapDog, you can use the provided uninstall.sh script or perform the steps manually.
Automated
You can run the following command to uninstall SwapDog using the script:
chmod +x uninstall.sh
./uninstall.sh
Manual
Take this as a documentation of the steps that the uninstall.sh script performs, so you can do it manually if you prefer:
- Stop the service with
sudo systemctl stop swapdog - Disable the service with
sudo systemctl disable swapdog - Remove the service file with
sudo rm /etc/systemd/system/swapdog.service - Remove the script with
sudo rm /usr/local/sbin/swapdog.py - Remove the configuration file with
sudo rm /etc/swapdog.json
sudo systemctl stop swapdog
sudo systemctl disable swapdog
sudo rm /etc/systemd/system/swapdog.service /usr/local/sbin/swapdog.py /etc/swapdog.json
sudo systemctl daemon-reload
Metadata
Release files for swapdog 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| swapdog-0.2.2.tar.gz | 19.3 kB | With provenance | Details for swapdog-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| swapdog-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for swapdog-0.2.2-py3-none-any.whl |
Total release size: 37.5 kB
Release files / swapdog-0.2.2.tar.gz
| Download URL | swapdog-0.2.2.tar.gz |
|---|---|
| Size | 19.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2c4e7174f554eeb7913b9fd91583ceaa59a4b61d126b67f10ff9699868d8d4a9
|
|
BLAKE2b-256 checksum How to use checksums |
02f4ffb8b33048127617b14f0592eb257ab323d5000f917c4cdb92a6b5823ccd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2025.
Transparency logRelease files / swapdog-0.2.2-py3-none-any.whl
| Download URL | swapdog-0.2.2-py3-none-any.whl |
|---|---|
| Size | 18.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eada4197c016fce80d4d146ef7f25383b01ab7d290de85962030586be2eea1c9
|
|
BLAKE2b-256 checksum How to use checksums |
3aa4b83141dfcbce6a641e4b98b87dcb02aa0133a822f51a6f6e1d2fcef870c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2025.
Transparency logSecurity for swapdog 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for swapdog-0.2.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2025.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.