# pycivitai
[](https://pypi.org/project/pycivitai/)
[](https://github.com/narugo1992/pycivitai/actions?query=workflow%3A%22Code+Test%22)
[](https://github.com/narugo1992/pycivitai/actions?query=workflow%3A%22Package+Release%22)
[](https://codecov.io/gh/narugo1992/pycivitai)
[](https://github.com/narugo1992/pycivitai/stargazers)
[](https://github.com/narugo1992/pycivitai/network)
[](https://github.com/narugo1992/pycivitai/issues)
[](https://github.com/narugo1992/pycivitai/pulls)
[](https://github.com/narugo1992/pycivitai/graphs/contributors)
[](https://github.com/narugo1992/pycivitai/blob/master/LICENSE)
Python Client and Model Management for civitai,
The design was inspired by [huggingface/huggingface_hub](https://github.com/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
```shell
pip install pycivitai
```
If you need TUI for manually deleting downloaded models, just install like this
```shell
pip install pycivitai[cli]
```
## Quick Start
### Use Model From CivitAI
`pycivitai` follows a similar usage pattern as the `huggingface_hub`, as shown below:
```python
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
```shell
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.
```python
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
```shell
pycivitai delete-cache -A # download all models
```
or use the TUI to choose which one to delete
```shell
pip install pycivitai[cli] # this step is necessary
pycivitai delete-cache
```
TUI is like this, build with [InquirerPy](https://github.com/kazhala/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.
Raw data
{
"_id": null,
"home_page": "https://github.com/narugo1992/pycivitai",
"name": "pycivitai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Python Client and Model Management for CivitAI.",
"author": "narugo1992",
"author_email": "narugo@126.com",
"download_url": "https://files.pythonhosted.org/packages/8f/82/a48e166bd026c1781e78a4cc6c193980ba6e163448624356006830aad54b/pycivitai-0.2.0.tar.gz",
"platform": null,
"description": "# pycivitai\n\n[](https://pypi.org/project/pycivitai/)\n\n\n\n\n[](https://github.com/narugo1992/pycivitai/actions?query=workflow%3A%22Code+Test%22)\n[](https://github.com/narugo1992/pycivitai/actions?query=workflow%3A%22Package+Release%22)\n[](https://codecov.io/gh/narugo1992/pycivitai)\n\n\n[](https://github.com/narugo1992/pycivitai/stargazers)\n[](https://github.com/narugo1992/pycivitai/network)\n\n[](https://github.com/narugo1992/pycivitai/issues)\n[](https://github.com/narugo1992/pycivitai/pulls)\n[](https://github.com/narugo1992/pycivitai/graphs/contributors)\n[](https://github.com/narugo1992/pycivitai/blob/master/LICENSE)\n\nPython Client and Model Management for civitai,\n\nThe design was inspired by [huggingface/huggingface_hub](https://github.com/huggingface/huggingface_hub), implementing\nautomatic management of downloaded models locally, and automatically detecting file changes and the latest versions.\n\n## Installation\n\nYou can install `pycivitai` with pip\n\n```shell\npip install pycivitai\n```\n\nIf you need TUI for manually deleting downloaded models, just install like this\n\n```shell\npip install pycivitai[cli]\n```\n\n## Quick Start\n\n### Use Model From CivitAI\n\n`pycivitai` follows a similar usage pattern as the `huggingface_hub`, as shown below:\n\n```python\nfrom pycivitai import civitai_download\n\nif __name__ == '__main__':\n # get the latest version of DEN_barbucci_artstyle (either model title or id is okay)\n # Homepage of this model: https://civitai.com/models/85716\n # the return value of civitai_download is the path of downloaded file you need\n print(civitai_download('DEN_barbucci_artstyle'))\n\n # get the same model (DEN_barbucci_artstyle) with model id\n print(civitai_download(85716))\n\n # get the specific version (either version name of id is okay)\n print(civitai_download('DEN_barbucci_artstyle', version='v1.0'))\n print(civitai_download('DEN_barbucci_artstyle', 91158))\n\n # This is a model with multiple files inside.\n # It contains a safetensors and a vae, the safetensors is primary.\n # Homepage of this model: https://civitai.com/models/6755/cetus-mix\n print(civitai_download('Cetus-Mix')) # the safetensors file (when file not specified, primary file will be chosen)\n print(civitai_download('Cetus-Mix', file='*.vae.pt')) # get the vae file\n\n```\n\nIf you are using command line, you can get the models with the following commands\n\n```shell\npycivitai get -m 'DEN_barbucci_artstyle' # get model, use primary file of the latest version\npycivitai get -m 'DEN_barbucci_artstyle' -v 'v1.0' # get model, use primary file the v1.0 version\npycivitai get -m 'Cetus-Mix' # get the safetensors file of Cetus-Mix\npycivitai get -m 'Cetus-Mix' -f '*.vae.pt' # get the vae file of Cetus-Mix\n\n```\n\n### Get Information of Model Resource\n\nIf you only need to obtain information about the model's resource files, for example, if you need to download the files\nyourself, you can use the `civitai_find_online` function, which will return a `Resource` object.\n\n```python\nfrom pycivitai import civitai_find_online, Resource\n\nif __name__ == '__main__':\n # get resource of this model file, arguments are the same as `civitai_download`\n resource: Resource = civitai_find_online('DEN_barbucci_artstyle')\n\n # information of this resource\n print(resource.model_name)\n print(resource.model_id)\n print(resource.version_name)\n print(resource.version_id)\n print(resource.filename)\n print(resource.url)\n print(resource.size)\n print(resource.sha256)\n print(resource.is_primary)\n\n```\n\n### Clear the Downloaded Models\n\nIf you need to delete all the local models, just\n\n```shell\npycivitai delete-cache -A # download all models\n```\n\nor use the TUI to choose which one to delete\n\n```shell\npip install pycivitai[cli] # this step is necessary\npycivitai delete-cache\n```\n\nTUI is like this, build with [InquirerPy](https://github.com/kazhala/InquirerPy):\n\n```\n? Choose model versions to delete:\n Model cetus_mix(ID: 6755, 2 files, size: 3.899 GiB):\n\u276f \u25cb cetusmix_whalefall2(ID: 105924, 2 files, size: 3.899 GiB)\n\n Model den_barbucci_artstyle(ID: 85716, 2 files, size: 17.181 KiB):\n \u25cb v1_0(ID: 91158, 1 file, size: 7.160 KiB)\n \u25cb v2_0(ID: 113049, 1 file, size: 10.021 KiB)\n```\n\n## F.A.Q.\n\n### Where will the downloaded model be saved?\n\nThe downloaded model will be saved by default in the `~/.cache/civitai` directory. If you need to change the save path,\nyou can set the value of the `CIVITAI_HOME` environment variable to your desired save path.\n\n### How are downloaded models managed?\n\nAfter downloading, the models are managed using the file system, and file locks are set to ensure thread safety during\nreading and writing. The structure is similar to the following:\n\n```\n~/.cache/civitai\n\u251c\u2500\u2500 cetus_mix__6755\n\u2502 \u2514\u2500\u2500 cetusmix_whalefall2__105924\n\u2502 \u251c\u2500\u2500 files\n\u2502 \u2502 \u251c\u2500\u2500 cetusMix_Whalefall2.safetensors\n\u2502 \u2502 \u2514\u2500\u2500 vae-ft-mse-840000-ema-pruned.vae.pt\n\u2502 \u251c\u2500\u2500 hashes\n\u2502 \u2502 \u251c\u2500\u2500 cetusMix_Whalefall2.safetensors.hash\n\u2502 \u2502 \u2514\u2500\u2500 vae-ft-mse-840000-ema-pruned.vae.pt.hash\n\u2502 \u2514\u2500\u2500 primary\n\u2514\u2500\u2500 den_barbucci_artstyle__85716\n \u251c\u2500\u2500 v1_0__91158\n \u2502 \u251c\u2500\u2500 files\n \u2502 \u2502 \u2514\u2500\u2500 DEN_barbucci_artstyle.pt\n \u2502 \u251c\u2500\u2500 hashes\n \u2502 \u2502 \u2514\u2500\u2500 DEN_barbucci_artstyle.pt.hash\n \u2502 \u2514\u2500\u2500 primary\n \u2514\u2500\u2500 v2_0__113049\n \u251c\u2500\u2500 files\n \u2502 \u2514\u2500\u2500 DEN_barbucci_styleMK2.pt\n \u251c\u2500\u2500 hashes\n \u2502 \u2514\u2500\u2500 DEN_barbucci_styleMK2.pt.hash\n \u2514\u2500\u2500 primary\n```\n\nThis structure does not have any additional dependencies. Therefore, when it is necessary to migrate the storage path,\nyou can simply move it and modify the environment variable `CIVITAI_HOME`.\n\n### What happens when in an offline environment?\n\nWhen a network anomaly or an offline environment is detected (such as connection errors or timeouts), the library will\nattempt to find a suitable model from the locally downloaded models to provide to the user. If no locally available\nmodel is found, an exception will be raised.\n\nAdditionally, if you are in a clearly offline environment and using pre-downloaded models, you can set the value of\nthe `CIVITAI_OFFLINE` environment variable to avoid attempts for network access.\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Python Client and Model Management for CivitAI.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/narugo1992/pycivitai"
},
"split_keywords": [
"python",
"client",
"and",
"model",
"management",
"for",
"civitai."
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6e3fefbfb36d4332064a883499ee68eac220e9127c20425f92a3e3d87d43f996",
"md5": "150b50de97e7ee4ae7c0c13e77409065",
"sha256": "be8489077db0cde49e63ec771a57604ac4fe305be6f86499133af0ba55ffd390"
},
"downloads": -1,
"filename": "pycivitai-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "150b50de97e7ee4ae7c0c13e77409065",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 27051,
"upload_time": "2024-03-24T15:46:29",
"upload_time_iso_8601": "2024-03-24T15:46:29.109146Z",
"url": "https://files.pythonhosted.org/packages/6e/3f/efbfb36d4332064a883499ee68eac220e9127c20425f92a3e3d87d43f996/pycivitai-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f82a48e166bd026c1781e78a4cc6c193980ba6e163448624356006830aad54b",
"md5": "fe77a286d58ea8beed73737c4dfddad5",
"sha256": "985fad1b6c693dad65e7d66d7b21932d153fbd605ebee041451b0765bdaa59cd"
},
"downloads": -1,
"filename": "pycivitai-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "fe77a286d58ea8beed73737c4dfddad5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 27149,
"upload_time": "2024-03-24T15:46:30",
"upload_time_iso_8601": "2024-03-24T15:46:30.341971Z",
"url": "https://files.pythonhosted.org/packages/8f/82/a48e166bd026c1781e78a4cc6c193980ba6e163448624356006830aad54b/pycivitai-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-24 15:46:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "narugo1992",
"github_project": "pycivitai",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "hbutils",
"specs": [
[
">=",
"0.9.1"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"7.0.0"
]
]
},
{
"name": "requests",
"specs": []
},
{
"name": "filelock",
"specs": []
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.42.1"
]
]
}
],
"lcname": "pycivitai"
}
JSON
