Skip to main content

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:

  1. Install dependencies with sudo pip3 install -r requirements.txt
  2. Copy the swapdog.py file to /usr/local/sbin/
  3. Make it executable with sudo chmod 744 /usr/local/sbin/swapdog.py
  4. Copy the swapdog.json file to /etc/
  5. Copy the swapdog.service file to /etc/systemd/system/
  6. Enable the service with sudo systemctl enable swapdog
  7. Start the service with sudo systemctl start swapdog
  8. 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/sda1 or /swapfile).
  • period: The time in seconds between checks of the RAM usage. Default is 1.0 seconds if not specified.
  • disable_swaps: A boolean flag that indicates whether to disable swaps when RAM usage is below the threshold. Default is false.
  • 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 is 10.0 if 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.json file 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:

  1. Stop the service with sudo systemctl stop swapdog
  2. Disable the service with sudo systemctl disable swapdog
  3. Remove the service file with sudo rm /etc/systemd/system/swapdog.service
  4. Remove the script with sudo rm /usr/local/sbin/swapdog.py
  5. 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)

Source distribution for swapdog 0.2.2
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)

Table of built distributions (wheels) for swapdog 0.2.2
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page