Working with packages

On this page:


Definitions

Packages

All files uploaded to Anaconda.org are stored in packages. You can view each Anaconda.org package at its own unique URL based on the user and package name.

Users can create an Anaconda.org package and then upload files into it. Both tar.bz2 and .conda compression files can be uploaded to Anaconda.org. See Using the .conda compression format for more information on the .conda format.

For more information on packages, see package.

Namespaces

A namespace is the part of Anaconda.org where a user or organization may host packages. For example, the user namespace https://anaconda.org/travis contains packages that were uploaded and shared by a user named travis.

For more information on namespaces, see Namespace.

Labels

A label is part of the URLs on Anaconda.org where conda looks for packages.

You can tag a package with one or more labels, or leave the package untagged to automatically apply the default main label.

For more information on labels, see Label.

Using package managers

Anaconda.org supports two types of packages: conda and Standard Python packages. To work with conda or Standard Python packages, you must use their corresponding subdomains:

  • To install conda packages from the user travis, use the repository URL https://conda.anaconda.org/travis
  • To install Standard Python packages from the user travis, use the repository URL https://pypi.anaconda.org/travis

Conda packages

Uploading conda packages

This example shows how to build and upload a conda package to Anaconda.org using conda build.

Use the terminal (Anaconda Prompt for Windows users) to perform the following steps:

  1. Before you start, install anaconda-client and conda-build:

    conda install anaconda-client conda-build

  2. Choose the repository for which you would like to build the package. In this example, we use a simple public conda test package:

    # Replace <PACKAGE_NAME> with the package name
git clone https://github.com/Anaconda-Platform/anaconda-client
cd anaconda-client/<PACKAGE_NAME>/conda/

    In this directory, there are two required files, meta.yaml and build.sh.

    macOS and Linux systems are Unix systems. Packages built for Unix systems require a build.sh file, packages built for Windows require a bld.bat file, and packages built for both Windows and Unix systems require both a build.sh file and a bld.bat file. All packages require a meta.yaml file.

  3. To build the package, turn off automatic Client uploading and then run the conda build command:

    conda config --set anaconda_upload no
conda build .

    All packages built in this way are placed in a subdirectory of the Anaconda conda-bld directory.

  4. You can check where the resulting file was placed with the --output option:

    conda build . --output

  5. You can upload the test package to Anaconda.org with the Anaconda upload command:

    anaconda login

# Replace </PATH/TO/PACKAGE_NAME> with the correct file path and package name
# Packages can be uploaded with .tar.bz2 or .conda compression formats
anaconda upload </PATH/TO/PACKAGE_NAME>.tar.bz2
anaconda upload </PATH/TO/PACKAGE_NAME>.conda

See Using the .conda compression format for more information on the .conda format.

For more information on conda’s overall build framework, you may also want to read the articles Building conda packages.

Installing conda packages

You can install conda packages from Anaconda.org by adding channels to your conda configuration.

Use the terminal (Anaconda Prompt for Windows users) to perform the following steps:

  1. Because conda knows how to interact with Anaconda.org, specifying the channel sean translates to https://anaconda.org/sean:

    conda config --add channels sean

  2. You can now install public conda packages from Sean’s Anaconda.org account. Try installing the testci package at https://anaconda.org/sean/testci:

    conda install testci

  3. You can install a package from a channel with a token and a label:

    # Replace <TOKEN> with the provided token
# Replace <CHANNEL> with a user channel
# Replace <LABEL_NAME> with the label name
# Replace <PACKAGE_NAME> with the name of the package you want to install
conda install -c https://conda.anaconda.org/t/<TOKEN>/<CHANNEL>/label/<LABEL_NAME> <PACKAGE_NAME>

Standard Python packages

Uploading Standard Python packages

We can test Standard Python package uploading with a small public example package saved in the anaconda-client repository.

Use the terminal (Anaconda Prompt for Windows users) to perform the following steps:

  1. Begin by cloning the repository from the command line:

    # Replace <PACKAGE_NAME> with the package name
git clone git@github.com:Anaconda-Platform/anaconda-client.git
cd anaconda-client/<PACKAGE_NAME>/pypi/

  2. You can now create your Standard Python package with the setup.py script:

    python setup.py sdist

  3. The package has now been built as a source tarball and is ready to be uploaded:

    anaconda upload dist/*.tar.gz

    Your package is now available at http://anaconda.org/<USERNAME>/<PACKAGE_NAME>, where <USERNAME> is your username and <PACKAGE_NAME> is the package name.

Installing Standard Python packages

The best way to install a Standard Python package is using pip. For the following command, we use the package we authored in the examples above. Open a terminal (Anaconda Prompt for Windows users) and run the following command:

# Replace <USERNAME> with your username
pip install --extra-index-url https://pypi.anaconda.org/<USERNAME>/simple pypi-test-package

Installing private Standard Python packages

The best way to manage access or make Standard Python packages and other packages private is to create organizations or groups, which allow you to set separate permissions per package, notebook, or environment.

You can also control access with the token system. All Anaconda.org URLs can be appended with /t/$TOKEN to access private packages.

Open a terminal (Anaconda Prompt for Windows users) and run the following command:

# Replace <TOKEN_NAME> with the name of the token you created
# Replace <USERNAME> with your username
# Replace <SIMPLE_TEST_PACKAGE> with the actual test-package name
TOKEN=$(anaconda auth --create --name <TOKEN_NAME>)
pip install --index-url https://pypi.anaconda.org/t/$TOKEN/<USERNAME>/<SIMPLE_TEST_PACKAGE>

Uploading packages

To upload package files to Anaconda.org, open a terminal (Anaconda Prompt for Windows users) and run the upload command:

# Replace <PACKAGE_NAME> with the package name
anaconda login
anaconda upload <PACKAGE_NAME>

Anaconda.org automatically detects packages and notebooks, package or notebook types, and their versions.

Your package is now available at http://anaconda.org/<USERNAME>/<PACKAGE_NAME>, where <USERNAME> is your username and <PACKAGE_NAME> is the package name.

Downloading packages

Your package can also be downloaded by anyone using Anaconda Client from the terminal (Anaconda Prompt for Windows users):

# Replace <USERNAME> with your username
# Replace <PACKAGE_NAME> with the package name
anaconda download <USERNAME>/<PACKAGE_NAME>

Editing package install instructions

After you have uploaded packages to an account or organization, you can control what install instructions appear on the your package’s download page. Install instructions will vary depending on the package’s labels or package type (conda or Standard Python).

To edit the visibility of your package install instructions:

  1. Click Edit.

    ../../../../../_images/org-package-install-instructions.png

  2. Check the boxes beside the instructions you don’t want to be visible. You can also check the checkbox on the far right of any group of instructions to hide all of them.

    ../../../../../_images/org-package-install-hide.png

  3. Click Save Changes.

    ../../../../../_images/org-package-install-instructions-final.png

Using private packages

It is no longer possible to sign up for an individual paid plan with private packages. Anyone who had private packages in the past still has the ability to have those hosted privately.

By default, all packages, notebooks, and environments uploaded to Anaconda.org are accessible to anyone who has access to the repository.


To mark packages uploaded to your user channel on Anaconda.org as private:

  1. Select the desired package.
  2. Navigate to the Settings tab.
  3. Select Admin in the sidebar.
  4. Select Private.

Note

  • Jupyter notebooks and conda environments can also be marked private using this procedure and URL.
  • Other Anaconda.org users may access your private packages either with tokens or by logging in.

Accessing private packages with tokens

To make your private packages accessible with tokens:

  1. First, create an access token that includes the following scope for Anaconda Client:

    conda:download

    Or, in the web UI:

    Allow private downloads from conda repositories

    The token is a random alphanumeric string and this is used to install a package or add a channel from which you want to install private packages.

  2. Using the provided token, a user channel can be added to config from the terminal (Anaconda Prompt for Windows users):

    # Replace <TOKEN> with the provided token
# Replace <CHANNEL> with a user channel
conda config --add channels https://conda.anaconda.org/t/<TOKEN>/<CHANNEL>

  3. The token can also be used to install packages without first adding the channel. In the terminal (Anaconda Prompt for Windows users), run:

    # Replace <TOKEN> with the provided token
# Replace <CHANNEL> with a user channel
# Replace <PACKAGE_NAME> with the name of the package you want to install
conda install -c https://conda.anaconda.org/t/<TOKEN>/<CHANNEL> <PACKAGE_NAME>

    To install a package from a channel using token and label name:

    # Replace <TOKEN> with the provided token
# Replace <CHANNEL> with a user channel
# Replace <LABEL_NAME> with the label name
# Replace <PACKAGE_NAME> with the name of the package you want to install
conda install -c https://conda.anaconda.org/t/<TOKEN>/<CHANNEL>/label/<LABEL_NAME> <PACKAGE_NAME>

  4. Private PyPI packages can also be installed in the web UI:

    # Replace <TOKEN> with the provided token
# Replace <CHANNEL> with a user channel
https://pypi.anaconda.org/t/<TOKEN>/<CHANNEL>

Accessing private packages with login

To make your private packages available to users who have logged in:

  1. Create an organization.
  2. Create a group (which can be read-only) in that organization..
  3. Add the desired users to the group.
  4. Upload the package to the organization, or transfer an existing package to the organization.

After you grant users access, other users can download and install your package using the web UI or Anaconda Client.

To download a package:

  1. In a browser, navigate to the desired channel.

  2. Open a terminal (Anaconda Prompt for Windows users) and run the following command:

    # Replace <ORGANIZATION> with the organization name
# Replace <PACKAGE_NAME> with the package name
conda install anaconda-client
anaconda login
conda install -c <ORGANIZATION> <PACKAGE_NAME>

    Or instead:

    # Replace <ORGANIZATION> with the organization name
# Replace <PACKAGE_NAME> with the package name
conda install anaconda-client
anaconda login
conda install -c https://conda.anaconda.org/<ORGANIZATION> <PACKAGE_NAME>

Removing a previous version of a package

To remove a previous version of one of your packages from Anaconda.org:

  1. Select the package name.
  2. Navigate to the Files tab.
  3. Select the checkbox to the left of the version you want to remove.
  4. In the Actions menu, select Remove.

To remove a previous version of one of your packages using the terminal (Anaconda Prompt for Windows users), run:

# Replace <USERNAME> with your username
# Replace <PACKAGE_NAME> with the package name
# Replace <VERSION_NUMBER> with the desired version
anaconda remove <USERNAME>/<PACKAGE_NAME>/<VERSION_NUMBER>

You can now see the change on your profile page at http://anaconda.org/<USERNAME>/<PACKAGE_NAME>, where <USERNAME> is your username and <PACKAGE_NAME> is the package name.

Adding a collaborator to a package

You can add other users that are not part of an organization to collaborate on your packages.

  1. From your dashboard, select the package.
  2. To display the package settings, select the Settings option.
  3. To display the current collaborators, select the Collaborators option.
  4. Enter the username of the person you want to add as a collaborator, then click Add.

Note

All collaborators are given full read/write permissions to the package, even for private packages.

Removing a collaborator from a package

To revoke package access previously granted to a collaborator:

  1. From your dashboard select the package.
  2. To display the package settings, select the Settings option.
  3. To display the current collaborators, select the Collaborators option.
  4. Click the red X next to a collaborator to revoke their access.

Transferring a package to a new owner

By default, when you create or add packages, they are attached to your individual profile. You can transfer ownership to another owner account you control, such as an organization profile you manage.

To transfer a package to a new owner:

  1. From your dashboard—or the dashboard of an organization you administer—select the package for which you want to transfer ownership. The system displays options for that package.
  2. To display the package settings, select the Settings option.
  3. Select the Admin option.
  4. Under Transfer this package to a new owner, click Transfer.
  5. Select the organization name for the new owner.
  6. Click Transfer Ownership.

Copying a package

The following command is an example of how to copy a package from the conda-forge channel to a personal channel called jsmith:

anaconda copy conda-forge/glueviz/0.10.4 --to-owner jsmith

conda-forge/glueviz/0.10.4 is a “spec” that can be formatted in one of two ways: user/package/version or user/package/version/filename.

Note

The anaconda copy commands from-channel and to-channel have been deprecated. If you attempt to run anaconda copy --from-channel conda-forge --to-channel jsmith glueviz, you will receive an error that Label conda-forge does not exist.

If the package glueviz/0.10.4 already exists for user jsmith, you will receive the following error message: File conflict while copying!. If you want to copy the package anyway, try prepending the command with one of the following flags:

  • --replace - allows you to overwrite an already existing package
  • --update - allows you to add missing metadata to an existing package

Deleting a package

To delete a package and all of its versions from Anaconda.org:

  1. Select the package name.
  2. Select the Settings option.
  3. Select the Admin option.
  4. Click Delete.

To delete a package and all of its versions using the terminal (Anaconda Prompt for Windows users), run:

# Replace <USERNAME> with your username
# Replace <PACKAGE_NAME> with the package name
anaconda remove <USERNAME>/<PACKAGE_NAME>

You can now see the change on your profile page at http://anaconda.org/<USERNAME>, where <USERNAME> is your username.

Using the .conda compression format

Currently, when you use conda build to create packages, those packages are compressed into a .tar.bz2 format. This format has been used since the inception of conda and has become very slow when compared to modern compression formats. With that in mind, the .conda compression format was created. See Conda packages and the Downloading and Extracting Packages section of the Understanding and Improving Conda’s Performance blog post for more detailed information on .conda.

The most important thing to understand about the .conda format is that it allows much faster access to packages’ metadata by compressing that metadata into its own tarball file separate from the rest of the package contents.

To see how the .conda format vastly improves the speed of package extraction, try the following:

#Install the conda-package-handling package
conda install conda-package-handling

#Transmute a .tar.bz2 package format into a .conda format
#cph transmute IN_FILE(file to convert) OUT_EXT(extention to convert to, i.e. .conda)
cph transmute mkl-2018.0.3-1.tar.bz2 .conda

#Test the speed of extracting the .tar.bz2 file versus the .conda file
$ time cph extract mkl-2018.0.3-1.tar.bz2 --dest mkl-a
cph extract mkl-2018.0.3-1.tar.bz2 --dest mkl-a  18.16s user 0.59s system 98% cpu 19.015 total
$ time cph extract mkl-2018.0.3-1.conda --dest mkl-b
cph extract mkl-2018.0.3-1.conda --dest mkl-b  1.41s user 0.65s system 87% cpu 2.365 total

As you can see the .conda file is extracted nearly an order of magnitude more quickly than the .tar.bz2 file.

.conda files can be uploaded to Anaconda.org using anaconda upload, just like any .tar.bz2 file. The current workflow for creating .conda packages is to build them using conda build, then transmute the .tar.bz2 files into .conda files using cph transmute, and then upload them normally as described in the uploading conda packages section.