0
# Volume Management
1

2
Docker volume creation, management, and data persistence operations. Volumes provide persistent data storage that survives container lifecycle changes and can be shared between containers.
3

4
## Capabilities
5

6
### Volume Creation and Configuration
7

8
Create volumes with specific drivers and configuration options.
9

10
```python { .api }
11
def create(
12
    name: Optional[str] = None,
13
    *,
14
    driver: Optional[str] = None,
15
    driver_options: Optional[Dict[str, str]] = None,
16
    labels: Optional[Dict[str, str]] = None
17
) -> Volume:
18
    """
19
    Create a new volume.
20
    
21
    Parameters:
22
    - name: Volume name (auto-generated if not provided)
23
    - driver: Volume driver (local, nfs, etc.)
24
    - driver_options: Driver-specific options
25
    - labels: Volume labels
26
    
27
    Returns:
28
    - Volume object
29
    """
30
```
31

32
### Volume Listing and Inspection
33

34
List and inspect volumes with filtering and detailed information retrieval.
35

36
```python { .api }
37
def list(
38
    filters: Optional[Dict[str, str]] = None,
39
    *,
40
    quiet: bool = False
41
) -> List[Volume]:
42
    """
43
    List volumes.
44
    
45
    Parameters:
46
    - filters: Filters to apply (dangling, driver, label, name)
47
    - quiet: Only show volume names
48
    
49
    Returns:
50
    - List of Volume objects
51
    """
52

53
def inspect(volume: str) -> Volume:
54
    """
55
    Get detailed information about a volume.
56
    
57
    Parameters:
58
    - volume: Volume name
59
    
60
    Returns:
61
    - Volume object with full details
62
    """
63
```
64

65
### Volume Cleanup
66

67
Remove volumes and clean up unused volumes.
68

69
```python { .api }
70
def remove(
71
    volumes: Union[str, List[str]],
72
    *,
73
    force: bool = False
74
) -> None:
75
    """
76
    Remove volumes.
77
    
78
    Parameters:
79
    - volumes: Volume name(s)
80
    - force: Force removal of volume
81
    """
82

83
def prune(filters: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
84
    """
85
    Remove unused volumes.
86
    
87
    Parameters:
88
    - filters: Filters to apply
89
    
90
    Returns:
91
    - Information about removed volumes
92
    """
93
```
94

95
## Usage Examples
96

97
### Basic Volume Operations
98

99
```python
100
from python_on_whales import docker
101

102
# Create a named volume
103
volume = docker.volume.create("my-data-volume")
104
print(f"Created volume: {volume.name}")
105

106
# List all volumes
107
volumes = docker.volume.list()
108
for vol in volumes:
109
    print(f"Volume: {vol.name} - Driver: {vol.driver}")
110

111
# Use volume in container
112
container = docker.run(
113
    "alpine:latest",
114
    ["sh", "-c", "echo 'Hello' > /data/test.txt && cat /data/test.txt"],
115
    volumes=["my-data-volume:/data"],
116
    remove=True
117
)
118
print(container)
119

120
# Remove volume
121
docker.volume.remove("my-data-volume")
122
```
123

124
### Advanced Volume Configuration
125

126
```python
127
# Create volume with driver options
128
nfs_volume = docker.volume.create(
129
    "nfs-storage",
130
    driver="local",
131
    driver_options={
132
        "type": "nfs",
133
        "o": "addr=192.168.1.100,rw",
134
        "device": ":/path/to/share"
135
    },
136
    labels={"environment": "production"}
137
)
138

139
# Create tmpfs volume
140
tmpfs_volume = docker.volume.create(
141
    "temp-data",
142
    driver="local",
143
    driver_options={
144
        "type": "tmpfs",
145
        "tmpfs-size": "1G"
146
    }
147
)
148

149
# Filter volumes by label
150
production_volumes = docker.volume.list(
151
    filters={"label": "environment=production"}
152
)
153

154
# Clean up unused volumes
155
prune_result = docker.volume.prune()
156
print(f"Removed {len(prune_result.get('VolumesDeleted', []))} volumes")
157
```
158

159
### Volume Backup and Restore
160

161
```python
162
# Backup volume data
163
backup_container = docker.run(
164
    "alpine:latest",
165
    ["tar", "czf", "/backup/data.tar.gz", "-C", "/data", "."],
166
    volumes=[
167
        "source-volume:/data:ro",
168
        "/host/backup:/backup"
169
    ],
170
    remove=True
171
)
172

173
# Restore volume data
174
restore_container = docker.run(
175
    "alpine:latest", 
176
    ["tar", "xzf", "/backup/data.tar.gz", "-C", "/data"],
177
    volumes=[
178
        "target-volume:/data",
179
        "/host/backup:/backup:ro"
180
    ],
181
    remove=True
182
)
183
```
184

185
## Types
186

187
```python { .api }
188
class Volume:
189
    name: str
190
    driver: str
191
    mountpoint: str
192
    created: str
193
    scope: str
194
    labels: Dict[str, str]
195
    options: Dict[str, str]
196
    
197
    def remove(self, force: bool = False) -> None: ...
198
    def reload(self) -> None: ...
199
```