pycivitai

Python Client and Model Management for civitai,

The design was inspired by huggingface/huggingface_hub, implementing automatic management of downloaded models locally, and automatically detecting file changes and the latest versions.

Installation

You can install pycivitai with pip

pip install pycivitai

If you need TUI for manually deleting downloaded models, just install like this

pip install pycivitai[cli]

Quick Start

Use Model From CivitAI

pycivitai follows a similar usage pattern as the huggingface_hub, as shown below:

from pycivitai import civitai_download

if __name__ == '__main__':
    # get the latest version of DEN_barbucci_artstyle (either model title or id is okay)
    # Homepage of this model: https://civitai.com/models/85716
    # the return value of civitai_download is the path of downloaded file you need
    print(civitai_download('DEN_barbucci_artstyle'))

    # get the same model (DEN_barbucci_artstyle) with model id
    print(civitai_download(85716))

    # get the specific version (either version name of id is okay)
    print(civitai_download('DEN_barbucci_artstyle', version='v1.0'))
    print(civitai_download('DEN_barbucci_artstyle', 91158))

    # This is a model with multiple files inside.
    # It contains a safetensors and a vae, the safetensors is primary.
    # Homepage of this model: https://civitai.com/models/6755/cetus-mix
    print(civitai_download('Cetus-Mix'))  # the safetensors file (when file not specified, primary file will be chosen)
    print(civitai_download('Cetus-Mix', file='*.vae.pt'))  # get the vae file

If you are using command line, you can get the models with the following commands

pycivitai get -m 'DEN_barbucci_artstyle'           # get model, use primary file of the latest version
pycivitai get -m 'DEN_barbucci_artstyle' -v 'v1.0' # get model, use primary file the v1.0 version
pycivitai get -m 'Cetus-Mix'                       # get the safetensors file of Cetus-Mix
pycivitai get -m 'Cetus-Mix' -f '*.vae.pt'         # get the vae file of Cetus-Mix

Get Information of Model Resource

If you only need to obtain information about the model's resource files, for example, if you need to download the files yourself, you can use the civitai_find_online function, which will return a Resource object.

from pycivitai import civitai_find_online, Resource

if __name__ == '__main__':
    # get resource of this model file, arguments are the same as `civitai_download`
    resource: Resource = civitai_find_online('DEN_barbucci_artstyle')

    # information of this resource
    print(resource.model_name)
    print(resource.model_id)
    print(resource.version_name)
    print(resource.version_id)
    print(resource.filename)
    print(resource.url)
    print(resource.size)
    print(resource.sha256)
    print(resource.is_primary)

Clear the Downloaded Models

If you need to delete all the local models, just

pycivitai delete-cache -A  # download all models

or use the TUI to choose which one to delete

pip install pycivitai[cli]  # this step is necessary
pycivitai delete-cache

TUI is like this, build with InquirerPy:

? Choose model versions to delete:
  Model cetus_mix(ID: 6755, 2 files, size: 3.899 GiB):
❯ ○ cetusmix_whalefall2(ID: 105924, 2 files, size: 3.899 GiB)

  Model den_barbucci_artstyle(ID: 85716, 2 files, size: 17.181 KiB):
  ○ v1_0(ID: 91158, 1 file, size: 7.160 KiB)
  ○ v2_0(ID: 113049, 1 file, size: 10.021 KiB)

F.A.Q.

Where will the downloaded model be saved?

The downloaded model will be saved by default in the ~/.cache/civitai directory. If you need to change the save path, you can set the value of the CIVITAI_HOME environment variable to your desired save path.

How are downloaded models managed?

After downloading, the models are managed using the file system, and file locks are set to ensure thread safety during reading and writing. The structure is similar to the following:

~/.cache/civitai
├── cetus_mix__6755
│   └── cetusmix_whalefall2__105924
│       ├── files
│       │   ├── cetusMix_Whalefall2.safetensors
│       │   └── vae-ft-mse-840000-ema-pruned.vae.pt
│       ├── hashes
│       │   ├── cetusMix_Whalefall2.safetensors.hash
│       │   └── vae-ft-mse-840000-ema-pruned.vae.pt.hash
│       └── primary
└── den_barbucci_artstyle__85716
    ├── v1_0__91158
    │   ├── files
    │   │   └── DEN_barbucci_artstyle.pt
    │   ├── hashes
    │   │   └── DEN_barbucci_artstyle.pt.hash
    │   └── primary
    └── v2_0__113049
        ├── files
        │   └── DEN_barbucci_styleMK2.pt
        ├── hashes
        │   └── DEN_barbucci_styleMK2.pt.hash
        └── primary

This structure does not have any additional dependencies. Therefore, when it is necessary to migrate the storage path, you can simply move it and modify the environment variable CIVITAI_HOME.

What happens when in an offline environment?

When a network anomaly or an offline environment is detected (such as connection errors or timeouts), the library will attempt to find a suitable model from the locally downloaded models to provide to the user. If no locally available model is found, an exception will be raised.

Additionally, if you are in a clearly offline environment and using pre-downloaded models, you can set the value of the CIVITAI_OFFLINE environment variable to avoid attempts for network access.