0
# Package Management
1

2
Install and manage MicroPython packages using the mip (MicroPython Package Installer) with support for multiple package sources including micropython-lib, GitHub, GitLab repositories, and custom package indexes.
3

4
## Capabilities
5

6
### Main Package Management Interface
7

8
Primary interface for package installation and management operations.
9

10
```python { .api }
11
def do_mip(state, args):
12
    """
13
    Main MIP package management command.
14
    
15
    Parameters:
16
    - state: State object with active transport
17
    - args: Package management arguments
18
    
19
    Args attributes:
20
    - command: List containing mip command ('install')
21
    - packages: List of package specifications to install
22
    - target: Optional target directory on device
23
    - index: Optional custom package index URL
24
    - mpy: Boolean to download compiled .mpy files (default True)
25
    """
26
```
27

28
### Package Installation
29

30
Install individual packages from various sources with dependency resolution and compilation options.
31

32
```python { .api }
33
def _install_package(transport, package, index, target, version, mpy):
34
    """
35
    Install single package from specified source.
36
    
37
    Parameters:
38
    - transport: Active device transport
39
    - package: Package specification string
40
    - index: Package index URL (None for default micropython-lib)
41
    - target: Target directory on device (None for default)
42
    - version: Package version constraint
43
    - mpy: Whether to prefer compiled .mpy files
44
    
45
    Package specifications:
46
    - "package_name": Install from default index
47
    - "package_name@version": Install specific version
48
    - "github:user/repo": Install from GitHub repository
49
    - "github:user/repo@branch": Install from specific branch
50
    - "gitlab:user/repo": Install from GitLab repository
51
    - "gitlab:user/repo@branch": Install from specific branch
52
    """
53
```
54

55
### JSON Package Installation
56

57
Install packages from JSON package descriptors with dependency management.
58

59
```python { .api }
60
def _install_json(transport, package_json_url, index, target, version, mpy):
61
    """
62
    Install package from JSON descriptor.
63
    
64
    Parameters:
65
    - transport: Device transport connection
66
    - package_json_url: URL to package.json descriptor
67
    - index: Package index URL
68
    - target: Installation target directory
69
    - version: Version constraints
70
    - mpy: Compile to .mpy format flag
71
    
72
    Handles dependency resolution and recursive installation.
73
    """
74
```
75

76
### File Download and Management
77

78
Download and manage package files with integrity checking and progress indication.
79

80
```python { .api }
81
def _download_file(transport, url, dest):
82
    """
83
    Download file from URL to device.
84
    
85
    Parameters:
86
    - transport: Active device transport
87
    - url: Source file URL
88
    - dest: Destination path on device
89
    
90
    Handles HTTP/HTTPS downloads with progress indication
91
    and automatic retry on failure.
92
    """
93

94
def _check_exists(transport, path, short_hash):
95
    """
96
    Check if file exists on device with hash validation.
97
    
98
    Parameters:
99
    - transport: Device transport
100
    - path: File path on device
101
    - short_hash: Expected file hash for validation
102
    
103
    Returns:
104
    - bool: True if file exists with correct hash
105
    """
106

107
def _ensure_path_exists(transport, path):
108
    """
109
    Ensure directory path exists on device.
110
    
111
    Parameters:
112
    - transport: Device transport
113
    - path: Directory path to create
114
    
115
    Creates parent directories as needed.
116
    """
117
```
118

119
### URL Processing
120

121
Process and rewrite URLs for accessing package repositories.
122

123
```python { .api }
124
def _rewrite_url(url, branch=None):
125
    """
126
    Rewrite GitHub/GitLab URLs for raw file access.
127
    
128
    Parameters:
129
    - url: Repository URL
130
    - branch: Optional branch specification
131
    
132
    Returns:
133
    - str: Rewritten URL for direct file access
134
    
135
    Converts repository URLs to raw content URLs
136
    for direct file downloading.
137
    """
138
```
139

140
## Command-Line Interface
141

142
### Basic Package Installation
143

144
```bash
145
# Install packages from micropython-lib
146
mpremote mip install aioble
147
mpremote mip install urequests asyncio
148

149
# Install multiple packages
150
mpremote mip install aioble urequests micropython-logging
151

152
# Install specific versions
153
mpremote mip install aioble@1.0.0
154
```
155

156
### GitHub and GitLab Installation
157

158
```bash
159
# Install from GitHub repositories
160
mpremote mip install github:micropython/micropython-lib
161
mpremote mip install github:user/awesome-micropython-lib
162

163
# Install from specific branches
164
mpremote mip install github:user/repo@development
165
mpremote mip install github:user/repo@feature-branch
166

167
# Install from GitLab
168
mpremote mip install gitlab:user/project
169
mpremote mip install gitlab:user/project@main
170
```
171

172
### Installation Options
173

174
```bash
175
# Install to specific target directory
176
mpremote mip install --target /lib aioble
177

178
# Use custom package index
179
mpremote mip install --index https://custom-index.com/packages aioble
180

181
# Install as source files (no .mpy compilation)
182
mpremote mip install --no-mpy urequests
183

184
# Force .mpy compilation (default)
185
mpremote mip install --mpy aioble
186
```
187

188
## Usage Examples
189

190
### Programmatic Package Installation
191

192
```python
193
from mpremote.main import State
194
from mpremote.mip import do_mip
195

196
# Set up connected device state
197
state = State()
198
# ... connect to device ...
199

200
# Install package programmatically
201
args = type('Args', (), {
202
    'command': ['install'],
203
    'packages': ['aioble', 'urequests'],
204
    'target': None,
205
    'index': None,
206
    'mpy': True
207
})()
208
do_mip(state, args)
209
```
210

211
### Custom Package Index
212

213
```bash
214
# Use private package repository
215
mpremote mip install --index https://company.com/micropython-packages asyncio-mqtt
216

217
# Install development versions
218
mpremote mip install --index https://dev-packages.micropython.org/latest experimental-driver
219
```
220

221
### Development Workflow Integration
222

223
```bash
224
# Install development dependencies
225
mpremote mip install --target /dev-lib unittest-micropython pytest-micropython
226

227
# Install from development repository
228
mpremote mip install github:developer/micropython-dev-tools@experimental
229

230
# Set up project dependencies
231
mpremote mip install \
232
  --target /lib \
233
  aioble \
234
  micropython-logging \
235
  urequests \
236
  github:project/custom-drivers@v2.1
237
```
238

239
## Package Sources and Formats
240

241
### MicroPython-lib (Default Index)
242

243
The default package source with curated MicroPython packages:
244

245
```bash
246
# Standard library packages
247
mpremote mip install asyncio
248
mpremote mip install logging
249
mpremote mip install unittest
250

251
# Networking packages  
252
mpremote mip install urequests
253
mpremote mip install umqtt.simple
254
mpremote mip install aioble
255

256
# Utility packages
257
mpremote mip install micropython-logging
258
mpremote mip install micropython-unittest
259
```
260

261
### GitHub Repositories
262

263
Install directly from GitHub repositories:
264

265
```bash
266
# Repository formats
267
mpremote mip install github:owner/repository
268
mpremote mip install github:owner/repository@branch
269
mpremote mip install github:owner/repository@tag
270

271
# Examples
272
mpremote mip install github:micropython/micropython-lib
273
mpremote mip install github:peterhinch/micropython-async@master
274
```
275

276
### GitLab Repositories
277

278
Install from GitLab repositories with same syntax:
279

280
```bash
281
# GitLab formats
282
mpremote mip install gitlab:owner/project
283
mpremote mip install gitlab:owner/project@branch
284

285
# Examples
286
mpremote mip install gitlab:company/micropython-drivers
287
mpremote mip install gitlab:team/iot-sensors@stable
288
```
289

290
### Custom Package Indexes
291

292
Use custom package repositories:
293

294
```bash
295
# Corporate package index
296
mpremote mip install --index https://packages.company.com/micropython device-drivers
297

298
# Development index
299
mpremote mip install --index https://dev.micropython.org/packages experimental-features
300
```
301

302
## Package Installation Process
303

304
### Installation Steps
305

306
1. **Package Resolution**: Resolve package name to download URL
307
2. **Dependency Analysis**: Parse package.json for dependencies  
308
3. **Download**: Fetch package files from source
309
4. **Compilation**: Optionally compile .py to .mpy files
310
5. **Installation**: Copy files to target directory on device
311
6. **Verification**: Validate file integrity and installation
312

313
### File Formats
314

315
- **.py files**: Source Python files
316
- **.mpy files**: Compiled MicroPython bytecode (faster import, smaller size)
317
- **package.json**: Package metadata and dependency information
318

319
### Target Directories
320

321
Default installation locations:
322
- **Root**: `/` (device root filesystem)
323
- **Library**: `/lib` (recommended for libraries)
324
- **Custom**: User-specified with `--target` option
325

326
## Error Handling
327

328
Package management operations may encounter various errors:
329

330
```python
331
from mpremote.transport import TransportError, TransportExecError
332

333
try:
334
    do_mip(state, args)
335
except TransportExecError as e:
336
    if "No space left" in e.error_output:
337
        print("Insufficient storage space on device")
338
    elif "404" in e.error_output:
339
        print("Package not found in repository")
340
    elif "Connection" in e.error_output:
341
        print("Network connection failed")
342
except TransportError as e:
343
    print(f"Device communication error: {e}")
344
```
345

346
### Common Error Scenarios
347

348
```bash
349
# Package not found
350
mpremote mip install nonexistent-package
351
# Error: Package not found in index
352

353
# Network connectivity issues
354
mpremote mip install github:user/private-repo
355
# Error: Repository not accessible
356

357
# Storage space issues
358
mpremote mip install large-package
359
# Error: No space left on device
360

361
# Version conflicts
362
mpremote mip install package@999.0.0
363
# Error: Version not available
364
```
365

366
## Best Practices
367

368
### Package Management Strategy
369

370
```bash
371
# Install to dedicated library directory
372
mpremote mip install --target /lib core-libraries
373

374
# Use version pinning for production
375
mpremote mip install aioble@1.2.3 urequests@0.6
376

377
# Prefer compiled packages for performance
378
mpremote mip install --mpy performance-critical-lib
379
```
380

381
### Development vs Production
382

383
```bash
384
# Development: source files for debugging
385
mpremote mip install --no-mpy --target /dev-lib debug-tools
386

387
# Production: compiled files for efficiency  
388
mpremote mip install --mpy --target /lib production-libs
389
```
390

391
### Dependency Management
392

393
```bash
394
# Install project dependencies from requirements
395
cat micropython-requirements.txt | while read package; do
396
    mpremote mip install "$package"
397
done
398

399
# Verify installations
400
mpremote exec "
401
import sys
402
print('Installed packages:')
403
for module in sys.modules:
404
    print(' ', module)
405
"
406
```