Join With an Empty String

What if you don’t want any separator at all, but just want toconcatenate the items? One valid approach is to use an empty string ("") as the separator:

>>>letters=["A","B","C","D"]>>>"".join(letters)'ABCD'

This code snippet concatenates the letters in the list, forming a single string"ABCD". Using an empty string as the separator is a great way to assemble strings without a delimiter between them.

Combine Strings of Characters

Since.join() can take any iterable of strings—not just lists—you can even pass a string as an argument. Because strings are iterable, Python iterates over each character in that string, considering each character as a separate element:

>>>characters="ABCD">>>",".join(characters)'A,B,C,D'

By calling.join() on"," and passing the stringcharacters, you effectively place a comma between every single character in"ABCD". This might not always be what you intend, but it’s a neat trick to keep in mind if you ever need to treat each character as a separate element.

Next, you’ll continue to explore using different separators when joining strings with.join().

Create Comma-Delimited Output

Suppose you have a list of fruit names that you want to pack into a single string with each fruit separated by a comma. You can handle this in one line:

>>>fruits=["apple","orange","lemon","kiwi"]>>>csv_line=",".join(fruits)>>>print(csv_line)apple,orange,lemon,kiwi

If you save or print this data to a file, you can handle it as a line in a basic CSV format. This approach is quick and efficient. However, keep in mind that if you need to handle quotes or complex CSV structures, then you should usePython’s dedicatedcsv library.

Collapse a List of URL Parts

Another use case for.join() is constructing or normalizing URL paths. Often, you’ll have a base domain and a list of subpaths that you want to concatenate with a slash (/):

base_url="https://example.com/"subpaths=["blog","2025","02","join-string"]full_url=base_url+"/".join(subpaths)print(full_url)

In this snippet, you start with a base URL, then use"/".join() to handle the rest.When you run the script, you’ll get a fully-formed URL as output:

$pythonurl_builder.pyhttps://example.com/blog/2025/02/join-string

If you need to handle more advanced URL operations, then you can also usePython’surllib library, specificallytheparse module, for robust URL manipulation.

Use Multicharacter Separators

Your separator doesn’t have to be a single character. You can also call.join() on a longer string if the delimiter you want has more than one character:

>>>colors=["red","green","blue"]>>>" | ".join(colors)'red | green | blue'

This code snippet uses the three-character string" | " as a delimiter.

Such a use case might make your output more visually appealing or help you parse the string quicker by picking a unique delimiter.

Because.join() doesn’t place any restrictions on the separator’s length or content, you’re free to choose any delimiter that best suits your data and user-facing output:

>>>running_instructions=("ready","set","go")>>>"...".join(running_instructions)'ready...set...go'

Joining values with.join() is one of the cleanest ways to convert a list of strings into a single output string. By calling.join() on the delimiter that you need—whether it’s a single character, a multicharacter substring, or even an empty string—you can unify your data in a single step.

Non-String Values in the Iterable

The most common error you’ll encounter when using.join() is aTypeError caused by trying to join an iterable that contains non-string values, such asintegers or floats:

>>>countdown=[3,2,1]>>>"-".join(countdown)Traceback (most recent call last):...TypeError:sequence item 0: expected str instance, int found

Python complains that the first element is an integer, not a string. The.join() method only works with strings, and it won’t automatically convert values to strings for you.

If you’re confronted with a situation where you want to join objects that aren’t strings, you can explicitly convert each element to a string beforehand using alist comprehension or agenerator expression andstr():

>>>countdown=[3,2,1]>>>"-".join(str(number)fornumberincountdown)'3-2-1'

Alternatively, you can use a morefunctional style with Python’smap() function:

>>>countdown=[3,2,1]>>>"-".join(map(str,countdown))'3-2-1'

Both approaches ensure that the resulting iterable you pass to.join() consists only of strings. Without these explicit conversions, Python willraise aTypeError because.join() doesn’t transform objects into strings automatically.

Non-Iterable Types

You can only pass an iterable object as an argument to.join(). If you pass a non-iterable object, such asNone or an integer, then Python will raise an error:

>>>"-".join(42)Traceback (most recent call last):...TypeError:can only join an iterable

Here, Python complains that42 isn’t an iterable, so.join() can’t loop over it and Python raises aTypeError.

If you’ve successfully done something like",".join("ABCD") in the past—passing a single string to.join()—then you might assume that passing just one integer or float would work the same way. A string may look like a single value, but Python treats it as asequence of characters, which means that it’s iterable.

Numbers, on the other hand, don’t implement theiterable protocol. As a result, passing them as arguments to.join() causes Python to raise aTypeError.

.join() Called on the Wrong Object

When you’re used to calling methods like.split() on the main string, it can feel counterintuitive that you need to call.join() on theseparator. When you accidentally reverse that order, you’ll get an unexpected result:

>>>"Hello World!".join(",")','

In this snippet, you’re calling.join() on"Hello World!", but passing just"," as the iterable. A string is an iterable of its characters, so.join() will attempt to place the separator string"Hello World!" in between every character of the"," string.

However, that string only consists of a single character, so there’s no place to insert the separator. Therefore,.join() returns a new string that only consists of",". This result may be surprising!

If you want to insert a single comma between each of the characters that make up the string"Hello, World!", then you need to swap the order of the strings involved:

>>>",".join("Hello World!")'H,e,l,l,o, ,W,o,r,l,d,!'

This confusion is especially common when you’re passing a single string as the argument to.join(), like in the example above. It’s a good idea to double-check that you always use"sep".join(iterable_of_strings) rather than accidentally reversing the order.

By understanding these pitfalls, you can avoid common mistakes when using.join(). Whether it’s converting non-string types or passing the correct iterable, a little awareness can save you time and frustration while debugging.

Pre-Pass: Check Types and Calculate Needed Space

Before doing any other work,CPython performs apre-pass that accomplishes two things:

1. Type Check: It checks whether all elements are strings.
2. Space Allocation: It calculates the total size of all items in the iterable, including the cumulative size of the separator, to create a new string with exactly the right size to fit all the pieces.

You can check out the actual implementation in the CPython source code in theunicodeobject.c file. There, you can find a function named_PyUnicode_JoinArray() that handles the low-level logic forPyUnicode_Join().

Below is a simplified snippet that shows the type check, and how the function calculates the total required size for the final joined string:

 1sz=0; 2seqlen=PySequence_Fast_GET_SIZE(seq); 3items=PySequence_Fast_ITEMS(seq); 4 5for(i=0;i<seqlen;i++){ 6item=items[i]; 7if(!PyUnicode_Check(item)){ 8/* If an element isn't a string, handle the error */ 9}10Py_ssize_titemlen=PyUnicode_GET_LENGTH(item);11sz+=itemlen;12}13if(seqlen>1){14sz+=seplen*(seqlen-1);15}

Remember that this is a simplified version of the original CPython code. You won’t find it just like this in the source code, but you can search for the variable names used above to see how they fit into the actual implementation.

Understanding what this code snippet does, however, can help when reading the actual source code:

• Line 1 defines the variablesz, short forsize, and sets it to0. You’ll update this variable to store the length of the final string that the join operation will produce.

• Lines 2 and 3 use specialized CPython functions to determine the size and collect the elements of the iterableseq. Note thatseq isn’t defined in the simplified code snippet above, but you’ll find it as a parameter in the original function in the source code.

• Lines 5 to 12 make up a loop that iterates over the items ofseq, checks whether they’re valid strings that CPython can concatenate, calculates the length of each element, and adds that length tosz, incrementing it accordingly.

• Lines 13 to 15 conditionally add the length of all necessary separators tosz. Because.join() adds the separator in between elements, you’ll needseqlen - 1 separators. This calculation is only relevant if there’s more than one item inseq and if you used a separator that’s larger than0 characters. Note that the simplified code snippet uses the variableseplen, which exists in the source code but isn’t defined above.

Using a similar but significantly more sophisticated approach, the real_PyUnicode_JoinArray() function determines the size of the string that the join operation will build. And because the runtime knows the total size (sz) beforehand, it can allocateexactly the required space for the final output when creating the initially empty, new string elementres:

/* ... */res=PyUnicode_New(sz,maxchar);

Creating a new object with the exact size requirements sets the stage for why.join() can be so efficient when you need to concatenate many items.

Second Pass: Copy Once and Insert Separators

After allocating the memory, CPython copies each string into the final buffer in order, inserting the separator as needed. Because of the setup work done during the pre-pass, it does this without needing to constantly re-create new objects.

Below you’ll find another simplified excerpt of the relevant CPython source code that you can study to better understand the high-level logic in_PyUnicode_JoinArray():

 1/* ... */ 2 3res_data=PyUnicode_1BYTE_DATA(res); 4sep_data=PyUnicode_1BYTE_DATA(sep); 5 6for(i=0;i<seqlen;i++){ 7item=items[i]; 8Py_ssize_titemlen=PyUnicode_GET_LENGTH(item); 9memcpy(res_data,10PyUnicode_DATA(item),11itemlen);12res_data+=itemlen;1314if(i<seqlen-1){15memcpy(res_data,16sep_data,17seplen);18res_data+=seplen;19}20}

Again, you won’t find this simplified code snippet in CPython’s source code, but it can be helpful to better understand the process that makes.join() efficient.

Assume that the variables from the previous step,res,sep,items,seqlen, andseplen are still accessible in this code:

• Line 3 creates apointer to the raw data buffer ofres. CPython later uses this value to keep track of where to insert the data.

• Line 4 does the same for the separator,sep. CPython uses this pointer to insert the separator’s data into the new string.

• Line 6 starts a loop that iterates over each item,line 7 fetches the current item, andline 8 calculates its length again.

• Lines 9 to 11 usememcpy() to insert the item’s data into the correct location inres, using theres_data pointer as the destination anditemlen to determine the size.

• Line 12 advances theres_data pointer by the length of the item.

• Line 14 checks whether you still need a separator, because you don’t need to add a separator after the last item of the iterable.

• Lines 15 to 19 then insert the separator, again usingmemcpy(), and advance the pointer accordingly.

After this pass over the elements in the iterable,res contains the data of all the elements interspersed with as many separators as necessary.

Using this two-step approach, CPython only needs to create one new string, removing the cost of making multiple partial copies. Further, becauseres is already the right size, CPython can directly copy each piece into the final position.

Compare.join() to Using+= in a Loop

Now, consider using theaugmented concatenation operator (+=) inside afor loop as another approach to joining strings:

cities=["Hanoi","Adelaide","Odessa","Vienna"]separator="->"travel_path=""fori,cityinenumerate(cities):travel_path+=cityifi<len(cities)-1:travel_path+=separatorprint(travel_path)

Here, each iteration needs to reallocate the result string,travel_path, to a new string object, copying previous data again and again. This results in a worst-case O(n²)time complexity.

# ...travel_path=travel_path+city# ...

The.join() method, on the other hand, runs in roughly O(n), because it examines all items first to calculate the total length, allocates once, then copies each substring and separator exactly once. Additionally, the code looks a lot more readable:

cities=["Hanoi","Adelaide","Odessa","Vienna"]travel_path="->".join(cities)print(travel_path)

The code injoin_concatenation.py produces the same result as the code inplus_loop_concatenation.py. But it’s also more straightforwardand more performant and scalable!

For a few short concatenations, you can use+, or f-strings. But once you’re handling an iterable of unknown length or find yourself joining strings in a loop,.join() remains the preferred andPythonic approach.