Command Line Usage

Command Line Usage#

This tutorial explains how to use the packing-packages command-line interface.

Basic Usage#

Display Help#

To see available commands and options, display the help:

packing-packages --help
packing-packages pack --help
packing-packages install --help

Check Version#

To check the current version:

packing-packages --version

pack Command#

The pack command packs a conda environment and all its dependencies into a directory.

Basic Usage#

To pack the currently active conda environment:

packing-packages pack
# same as
packing-packages pack -d .

This will save the packages to the current directory (.) with the following structure:

.
└── <envname>/
    ├── conda/
    │   ├── python-3.11.0-h1234567_0.tar.bz2
    │   ├── numpy-1.24.3-py311h1234567_0.conda
    │   ├── pandas-2.0.0-py311h1234567_0.tar.bz2
    │   └── ...
    └── pypi/
        ├── requests-2.31.0-py3-none-any.whl
        ├── beautifulsoup4-4.12.2-py3-none-any.whl
        ├── somepackage-1.0.0.tar.gz
        └── ...

Directory Structure:

  • <envname>/: Directory named after the conda environment

    • conda/: Contains conda packages (.tar.bz2 or .conda files)

    • pypi/: Contains PyPI packages (.whl or .tar.gz files)

Options#

-n, --env-name#

Specify the name of the conda environment to pack. If not specified, the currently active environment is used.

packing-packages pack -n myenv -d ./packages

-d, --dirpath-target#

Specify the path to the directory where the packed environment will be saved. Defaults to the current directory (.).

packing-packages pack -d /path/to/output

This creates the following structure:

/path/to/output/
└── <envname>/
    ├── conda/
    │   └── *.tar.bz2, *.conda files
    └── pypi/
        └── *.whl, *.tar.gz files

-D, --dry-run#

Perform a dry run without actually packing the environment. Useful for testing.

packing-packages pack -d . --dry-run

--diff-only#

Skip packages that already exist in the target directory and only download new packages.

packing-packages pack -d . --diff-only

-e, --encoding#

Specify the encoding to use for subprocess execution. If not specified, the system default encoding is used.

packing-packages pack -d . -e utf-8

Examples#

# Pack the current environment to the current directory
packing-packages pack -d .

# Pack a specific environment
packing-packages pack -n myenv -d ./myenv_packages

# Check with a dry run
packing-packages pack -n myenv -d ./myenv_packages --dry-run

# Skip existing packages and download only differences
packing-packages pack -n myenv -d ./myenv_packages --diff-only

pack yaml Command#

The pack yaml command packs packages directly from a conda environment file (.yaml). It can be executed on a different OS.

Basic Usage#

packing-packages pack yaml /path/to/environment.yaml

Options#

filepath_yaml (required)#

Specify the path to the conda environment file (.yaml).

packing-packages pack yaml environment.yaml

The output structure is the same as the pack command:

.
└── <envname>/          # Default: directory name from YAML or current directory
    ├── conda/
    │   └── *.tar.bz2, *.conda files
    └── pypi/
        └── *.whl, *.tar.gz files

-p, --platform#

Specify the platform. Choose one of the following:

  • win-64

  • win-32

  • linux-64

  • linux-aarch64

  • linux-ppc64le

  • linux-s390x

  • osx-64

  • osx-arm64

packing-packages pack yaml environment.yaml -p linux-64

-d, --dirpath-target#

Specify the path to the directory where the packed environment will be saved. Defaults to the current directory (.).

packing-packages pack yaml environment.yaml -p linux-64 -d ./packages

-D, --dry-run#

Perform a dry run without actually packing the environment.

packing-packages pack yaml environment.yaml -p linux-64 --dry-run

--diff-only#

Skip packages that already exist in the target directory and only download new packages.

packing-packages pack yaml environment.yaml -p linux-64 --diff-only

-e, --encoding#

Specify the encoding to use for subprocess execution.

packing-packages pack yaml environment.yaml -p linux-64 -e utf-8

Examples#

# Pack from a YAML file with platform specification
packing-packages pack yaml environment.yaml -p linux-64

# Specify output directory
packing-packages pack yaml environment.yaml -p linux-64 -d ./output

# Check with a dry run
packing-packages pack yaml environment.yaml -p linux-64 --dry-run

install Command#

The install command installs packed packages into a conda environment.

Basic Usage#

To install packages into the currently active conda environment:

packing-packages install .

Options#

DIRPATH_PACKAGES (positional argument)#

Specify the path to the directory containing packages to install. This should point to the directory containing the conda/ and pypi/ subdirectories (or the parent directory containing the environment-named folder). Defaults to the current directory (.) if not specified.

packing-packages install /path/to/packages

Expected directory structure:

/path/to/packages/          # Can be either:
├── conda/                  # Option 1: Direct access to conda/ and pypi/
│   └── *.tar.bz2, *.conda
└── pypi/
    └── *.whl, *.tar.gz

# OR

/path/to/packages/
└── <envname>/              # Option 2: Environment-named directory
    ├── conda/
    │   └── *.tar.bz2, *.conda
    └── pypi/
        └── *.whl, *.tar.gz

The command automatically detects and installs packages from both conda/ and pypi/ subdirectories.

-n, --env-name#

Specify the name of the conda environment where packages will be installed. If not specified, the currently active environment is used.

packing-packages install . -n myenv

-e, --encoding#

Specify the encoding to use for subprocess execution. If not specified, the system default encoding is used.

packing-packages install . -e utf-8

--generate-scripts#

Generate install scripts (install_packages.bat, install_packages.sh) instead of installing packages directly. These scripts can be distributed and used independently.

packing-packages install ./packages --generate-scripts

Generated files:

  • install_packages.bat: Windows batch script

  • install_packages.sh: Unix/Linux shell script

Directory structure after generation:

./packages/
├── conda/
│   └── *.tar.bz2, *.conda
├── pypi/
│   └── *.whl, *.tar.gz
├── install_packages.bat      # Generated
└── install_packages.sh       # Generated

--output-dir#

Specify the output directory for generated scripts. If not specified, scripts are written to the package directory.

packing-packages install ./packages --generate-scripts --output-dir ./scripts

Resulting structure:

./packages/
├── conda/
│   └── *.tar.bz2, *.conda
└── pypi/
    └── *.whl, *.tar.gz

./scripts/
├── install_packages.bat      # Generated here
└── install_packages.sh       # Generated here

Examples#

# Install packages into the current environment
packing-packages install .

# Install into a specific environment
packing-packages install ./packages -n myenv

# Generate install scripts
packing-packages install ./packages --generate-scripts

# Generate scripts with environment name and output directory specified
packing-packages install /path/to/packages \
  --generate-scripts \
  --env-name myenv \
  --output-dir /path/to/output

Practical Examples#

Source Device (Online Environment)#

  1. Activate the conda environment:

conda activate myenv

  1. Install packing-packages:

python -m pip install packing-packages

  1. Pack the environment:

python -m packing_packages pack -d .

This creates the following structure:

.
└── myenv/
    ├── conda/
    │   ├── python-3.11.0-h1234567_0.tar.bz2
    │   ├── numpy-1.24.3-py311h1234567_0.conda
    │   └── ...
    └── pypi/
        ├── requests-2.31.0-py3-none-any.whl
        └── ...

Or from a YAML file:

python -m packing_packages pack yaml environment.yaml -p linux-64

This creates the same structure, but packages are downloaded for the specified platform (linux-64 in this example).

Destination Device (Offline Environment)#

Method 1: Using Standard Install Commands#

Assuming you have the packed environment structure:

./myenv/
├── conda/
│   └── *.tar.bz2, *.conda
└── pypi/
    └── *.whl, *.tar.gz

# Create the environment
conda create -yn myenv --offline
conda activate myenv

# Install conda packages
conda install --use-local --offline ./myenv/conda/*

# Install pip packages
python -m pip install --no-deps --no-build-isolation ./myenv/pypi/*

Method 2: Using Generated Install Scripts#

If you generated scripts on the source device using --generate-scripts, you’ll have:

./myenv/
├── conda/
│   └── *.tar.bz2, *.conda
├── pypi/
│   └── *.whl, *.tar.gz
├── install_packages.bat
└── install_packages.sh

On the destination device:

# Windows
cd myenv
install_packages.bat

# Unix/Linux
cd myenv
./install_packages.sh

Method 3: Using packing-packages install#

If packing-packages is installed on the destination device:

conda create -yn myenv --offline
conda activate myenv
packing-packages install ./myenv

This automatically detects and installs packages from both conda/ and pypi/ subdirectories.

Troubleshooting#

Encoding Issues#

If encoding errors occur in certain environments, explicitly specify the encoding with the -e option:

packing-packages pack -d . -e utf-8
packing-packages install . -e utf-8

Proxy Configuration#

If you are in an environment that requires a proxy, set the environment variables:

export HTTP_PROXY="your proxy"
export HTTPS_PROXY="your proxy"

Handling Installation Errors#

The packing-packages install command skips packages that fail and continues. Check the error logs and install them manually if necessary.